Reconcile transactions via API
Learn how to use the Reconcile API to track and resolve transaction discrepancies, including timeouts, errors, and chargebacks, improving reporting and payment processing accuracy.
The Reconcile API allows you to retrieve data about transactions, useful for tracking those that have timed out, returned errors, or been chargebacked. You can reconcile transactions using two methods: by single transaction, where you can use unique_id
, Acquirer Reference Number (arn
), or transaction_id
, or by date range to fetch multiple transactions within a specified period.
Reconcile by Single Transaction
The Reconcile by Single Transaction method allows you to retrieve data about a specific transaction using its unique identifier (unique_id
), Acquirer Reference Number (ARN
), or merchant-specific transaction ID (transaction_id
). This method is ideal for troubleshooting or getting an update on the status of a particular transaction, such as when it times out, returns an error, or has been chargebacked.
Request parameters for reconciliation by single transaction
Parameter | Required | Format | Description |
---|---|---|---|
unique_id |
Yes | string (255) | The unique identifier for the transaction, generated by the payment system. |
arn |
Yes | string (255) | Acquirer Reference Number (ARN), used to uniquely identify a transaction from the acquirer. |
transaction_id |
Yes | string (255) | The unique ID provided by the merchant for tracking the transaction. |
Reconcile request examples
- By Unique Id
Reconcile a single transaction by providing the unique_id
.
Request example:
curl https://username:76042a13ce4cc9cb420b72bab79adf14201b2c8d@staging.gate.emerchantpay.net/reconcile/TERMINAL-TOKEN \
-X POST \
-H “Content-Type: text/xml” \
-d ‘
<?xml version=”1.0″ encoding=”UTF-8″?>
<reconcile>
<unique_id>44177a21403427eb96664a6d7e5d5d48</unique_id>
</reconcile>
Use the arn
(Acquirer Reference Number) to reconcile the transaction.
Request example:
curl https://username:76042a13ce4cc9cb420b72bab79adf14201b2c8d@staging.gate.emerchantpay.net/reconcile/TERMINAL-TOKEN \
-X POST \
-H “Content-Type: text/xml” \
-d ‘
<?xml version=”1.0″ encoding=”UTF-8″?>
<reconcile>
<arn>74537605248535042582882</arn>
</reconcile>
Alternatively, reconcile a transaction by providing the transaction_id
.
Request example:
curl https://username:76042a13ce4cc9cb420b72bab79adf14201b2c8d@staging.gate.emerchantpay.net/reconcile/TERMINAL-TOKEN \
-X POST \
-H “Content-Type: text/xml” \
-d ‘
<?xml version=”1.0″ encoding=”UTF-8″?>
<reconcile>
<transaction_id>merchant-transaction-id-here</transaction_id>
</reconcile>
XML response examples for reconciliation by single transaction
The response is a standard payment response, similar to the one you’d get from a transaction request. It can include the status of the transaction (e.g., approved, declined, pending) along with other relevant details.
Response parameters:
Parameter | Required | Format | Description |
---|---|---|---|
transaction_type |
Yes | string (255) | The type of transaction (e.g., sale, refund, authorize). |
status |
Yes | string (255) | The current status of the transaction (e.g., approved, declined, pending). |
unique_id |
Yes | string (255) | The unique identifier for the transaction. |
transaction_id |
Yes | string (255) | The transaction ID for the merchant’s reference. |
amount |
Yes | integer | The amount involved in the transaction. |
currency |
Yes | string (3) | The currency used for the transaction (e.g., USD, EUR). |
descriptor |
Yes | string (255) | A description of the transaction. |
payment_response |
Yes | string (255) | Shows the response status, which can include messages or technical data like threeds, message. |
sca_exemption_result |
No | string (255) | The result of the SCA exemption, if applicable. |
Response example:
<payment_response>
<transaction_type>sale</transaction_type>
<status>approved</status>
<authorization_code>005645</authorization_code>
<retrieval_reference_number>016813015184</retrieval_reference_number>
<payment_account_reference>Q1HJZ28RKA1EBL470G9XYG90R5D3E</payment_account_reference>
<response_code>00</response_code>
<unique_id>44177a21403427eb96664a6d7e5d5d48</unique_id>
<transaction_id>119643250547501c79d8295</transaction_id>
<mode>live</mode>
<timestamp>2025-05-12T14:50:59Z</timestamp>
<descriptor>Descriptor one</descriptor>
<amount>9000</amount>
<currency>USD</currency>
<card_brand>visa</card_brand>
<card_number>420000…0000</card_number>
<card_type>CREDIT</card_type>
<card_subtype>CARD SUBTYPE</card_subtype>
<card_issuing_bank>Issuing Bank</card_issuing_bank>
<card_issuing_country>Exact Issuing country</card_issuing_country>
<bank_account_number>Bank Account Number</bank_account_number>
<bank_identifier_code>Bank Identifier Code</bank_identifier_code>
<sent_to_acquirer>true</sent_to_acquirer>
<arn>74537605259536043849425</arn>
<scheme_response_code>00</scheme_response_code>
<scheme_transaction_link_id>TLINKIDENTIFIER4521412</scheme_transaction_link_id>
<scheme_max_settlement_date>2024-07-31</scheme_max_settlement_date>
<scheme_authentication_data_quality>true</scheme_authentication_data_quality>
<payment_response>threeds</payment_response>
<payment_response>technical_message</payment_response>
<payment_response>message</payment_response>
<payment_response>code</payment_response>
<scheme_transaction_identifier>019091214161031</scheme_transaction_identifier>
<scheme_settlement_date>0513</scheme_settlement_date>
<reason_for_not_honoring_exemption>8A01</reason_for_not_honoring_exemption>
<sca_exemption_result>13</sca_exemption_result>
</payment_response>
Reconcile by Date Range
If you need to reconcile multiple transactions over a specific period, you can use the Reconcile by Date Range method. This method allows you to fetch all transactions from a terminal within a given date range. The response is paginated, with each request returning up to 100 entries.
Request parameters for reconciliation by date range
Parameter | Required | Format | Description |
---|---|---|---|
start_date |
Yes | yyyy-mm-dd hh:mm:ss | Start of the requested date range (time is optional). |
end_date |
No | yyyy-mm-dd hh:mm:ss | End of the requested date range (time is optional). |
page |
No | integer | The page within the paginated result, defaults to 1. |
Request example:
curl https://username:76042a13ce4cc9cb420b72bab79adf14201b2c8d@staging.gate.emerchantpay.net/reconcile/by_date/TERMINAL-TOKEN \
-X POST \
-H “Content-Type: text/xml” \
-d ‘
<?xml version=”1.0″ encoding=”UTF-8″?>
<reconcile>
<start_date>2014-01-01 09:20:00</start_date>
<end_date>2014-01-31 21:30:00</end_date>
<page>2</page>
</reconcile>
XML response examples for reconciliation by date range
The response includes a paginated list of all transactions within the specified date range. Each page will contain up to 100 entries.
Response parameters:
Parameter | Required | Format | Description |
---|---|---|---|
per_page |
Yes | integer | The number of entries returned per page (e.g., 100). |
page |
Yes | integer | The current page of the results (defaults to 1). |
total_count |
Yes | integer | The total number of entries available in the full dataset. |
pages_count |
Yes | integer | The total number of pages available for the result set. |
transaction_type |
Yes | string (255) | The type of transaction (e.g., sale, refund, authorize). |
status |
Yes | string (255) | The current status of the transaction (e.g., approved, declined, pending). |
unique_id |
Yes | string (255) | The unique identifier for the transaction. |
transaction_id |
Yes | string (255) | The transaction ID for the merchant’s reference. |
amount |
Yes | integer | The amount involved in the transaction. |
currency |
Yes | string (3) | The currency used for the transaction (e.g., USD, EUR). |
descriptor |
Yes | string (255) | A description of the transaction. |
payment_response |
Yes | string (255) | Shows the response status, which can include messages or technical data like threeds, message. |
sca_exemption_result |
No | string (255) | The result of the SCA exemption, if applicable. |
Response example:
<payment_responses per_page=”100″ page=”2″ total_count=”19″ pages_count=”7″>
<payment_response>
<transaction_type>sale</transaction_type>
<status>approved</status>
<authorization_code>005645</authorization_code>
<scheme_response_code>00</scheme_response_code>
<response_code>00</response_code>
<crypto>true</crypto>
<unique_id>130319cfb3bf65ff3c4a4045487b174f</unique_id>
<transaction_id>EFBFBC7D-82CD-4375-9A69-15F19C88A134</transaction_id>
<technical_message>Transaction successful!</technical_message>
<message>Transaction successful!</message>
<mode>live</mode>
<timestamp>2014-01-03T15:04:00Z</timestamp>
<descriptor>descriptor one</descriptor>
<amount>500</amount>
<currency>USD</currency>
<card_brand>visa</card_brand>
<card_number>420000…0000</card_number>
<card_holder>John Doe</card_holder>
<expiration_year>2020</expiration_year>
<expiration_month>2</expiration_month>
<sent_to_acquirer>true</sent_to_acquirer>
<reason_for_not_honoring_exemption>8A01</reason_for_not_honoring_exemption>
<sca_exemption_result>13</sca_exemption_result>
</payment_response>
<!– Additional payment responses will follow here –>
</payment_responses>