# Clearing API
source: https://developer.mastercard.com/transaction-notifications/documentation/api-reference/clearing/index.md

## Overview {#overview}

The Clearing API enables third party applications to obtain clearing data from consumers, contingent upon the explicit consent provided by the consumer. Clearing data is also not available in real-time; instead, updates occur at periodic intervals following transaction settlements.

Clearing data is beneficial in situations where there is a difference between the authorized transaction amount, such as a restaurant bill with the addition of a tip.

## OpenAPI Specification {#openapi-specification}

**For an API request, only the following input combinations will be accepted:**   

1. A single transaction lookup through specifying *transUid* (from auth notification)  
2. Multiple transactions through a date range i.e. (*transactionStartDate* , *transactionEndDate* )  
3. Multiple transactions after a certain date i.e. _afterTransactionDate_  
4. All clearing records as they are created using a cursor (see below)

The API supports retrieving multiple objects via pagination. Thus, the parameters in the request URI should include an offset and limit. The offset is the starting point of the transaction data while the limit is the amount of data that will be given back to the user. An example of this is Offset=200, Limit=100, which will result in obtaining the 200th-300th transaction if there are more than 300, and if there are less, it will return up to the last transaction.

{#start-consents-auth}


API Reference: `POST /notifications/transactions/search`

<br />

Refer to [OpenAPI Specification](https://developer.mastercard.com/transaction-notifications/documentation/api-reference/endpoints/index.md#openapi-specification) for API specifications.

## Reading clearing data using a cursor {#reading-clearing-data-using-a-cursor}

To read all clearing data as it becomes available, you can call the API
periodically, using a cursor to keep track of the records you have already read.

In the first call, pass the cursor value "0". This will return the oldest clearing
record to the *limit* set in the API request. The response contains a property *nextClearingCursor* . Pass this value as the
cursor in the next API call to get the next *limit* records.

## Clearing notifications {#clearing-notifications}

Clearing webhook notifications can be enabled, similar to auth notifications. The event
sent to the webhook contains single property *clearing* which is a list of clearing
events. The clearing events are the same as the objects returned in the clearing search
API above.

Outbound calls are sent from Mastercard to an endpoint exposed by you to
notify you of clearing records when they become available on a periodic basis.

Example notification body

```json
{
    "clearing": [
        {
          "cardReference": "47r45e73-7dwe-43f9-bk6b-5096F5reb5cd",
          "referenceNumber": "MCFO9EC2A",
          "transactionAmount": 12.34,
          "transactionCurrency": "USD",
          "transactionLocalDate": "2024-24-04",
          "transactionLocalTime": "16:01:00",
          "settlementDate": "2024-04-26",
          "transactionType": "05",
          "merchantName": "CENTRA",
          "cardAcceptorCity": "NEW YORK",
          "cardAcceptorState": "NY",
          "merchantCountryCode": "USA",
          "merchantCategoryCode": "4111",
          "acquirerId": "123456",
          "transUid": "20240426O9EC2A",
          "cardholderAmount":12.34,
          "cardholderCurrency":"USD",
          "financialNetworkCode":"MCF",
          "processDate":"2024-04-25",
          "clearingUniqueId":"202404261024009777553",
          "functionCode":"200",
          "messageReasonCode":"1401",
          "banknetDate":"0424"
        }
    ]
}
```