Retrieve payment authorisations via API
Retrieve authorisation-level data via API to reconcile transactions, investigate declines, and feed your reporting or BI tools.
The Payment Authorisations API allows you to download a comprehensive list of authorisations processed through your emerchantpay merchant account. Use it to:
✅ reconcile settlement totals against your internal records✅ investigate declines or high AVS / CVV failure rates
✅ feed authorisation‑level data into your BI or reporting stack
Each record includes key details such as authorisation codes, masked card numbers, currency, amounts, and issuer response status.
To check the current status of a specific payment, see the Reconcile API.
For the full API details, see the Payment Authorizations API.
Prerequisites
Before retrieving payment authorisations, ensure you have:
- Gateway credentials – either your API username/password or a token issued by tech-support@emerchantpay.com. tech-support@emerchantpay.com.
- A tool that can POST XML over HTTPS – for example cURL, Postman, or Insomnia.
- (Optional) Basic scripting skills – helpful for looping through paginated results and parsing the XML if you plan to automate exports.
Construct the API request
Request parameters:
Parameter | Required | Format | Description |
---|---|---|---|
start_date |
✅ Yes* | yyyy-mm-dd | First calendar day to include by creation date. |
end_date |
❌ No | yyyy-mm-dd | Last calendar day to include by creation date. |
auth_start_date |
✅ Yes* | yyyy-mm-dd | First day to include by authorisation date. |
auth_end_date |
❌ No | yyyy-mm-dd | Last day to include by authorisation date. |
page |
❌ No | integer | Page number for pagination (defaults to 1). |
per_page |
❌ No | integer | Records returned per page (defaults to 100, max 100). |
externally_processed |
❌ No | string (255) |
Filter by processing source: genesis , external , or all (default genesis ). |
processing_type |
❌ No | string (255) |
Filter by channel: card_present , card_not_present , or all (default all ). |
start_date
or auth_start_date
(or both) must be supplied.
Request example:
curl https://staging.gate.emerchantpay.net/payment_authorizations/by_date \
-X POST \
-H “Content-Type: text/xml” \
-d ‘
<?xml version=”1.0″ encoding=”UTF-8″?>
<payment_authorization_request>
<start_date>2014-01-01</start_date>
<end_date>2014-01-31</end_date>
<auth_start_date>2014-01-01</auth_start_date>
<auth_end_date>2014-01-31</auth_end_date>
<externally_processed>external</externally_processed>
<processing_type>all</processing_type>
<page>1</page>
</payment_authorization_request>
Understand the API response
Response parameters:
Field | Type | Description |
---|---|---|
merchant_number |
string | Your emerchantpay merchant ID. |
record_number |
string | Unique identifier assigned to the authorisation transaction by the gateway. |
card_number |
string | Masked card number (first 6 and last 4 digits only). |
currency |
string (3) | Three-letter ISO 4217 currency code. |
amount |
integer | Authorised amount in minor currency units (e.g. cents, pence). |
auth_code |
string (6) | Six-character authorisation code issued by the card scheme. |
auth_date |
string | Date and time when the authorisation was issued, in UTC. |
resp_code | string | |
reversed |
Y / N | “Y” if the authorisation was later voided or reversed, “N” otherwise. |
pos_entry_mode |
string (3) | Indicates how the card was entered (e.g. 101 = manual, 102 = magstripe). |
voice |
Y / N | “Y” if this was a voice-authorised transaction. |
avs_result |
string (1) | Result of the AVS (Address Verification Service) check. |
cvv2_result |
string (1) | Result of the CVV2 security code check. |
card_type |
string (1) | Card scheme code (e.g. V = Visa, M = Mastercard). |
ecom_type |
string (5) | Indicator for e-commerce transactions; empty for card-present. |
eci_sli |
string (2) | ECI (Visa) or SLI (Mastercard) code for online transactions. |
rrn |
string (12) | Retrieval Reference Number assigned by the issuer. |
card_acceptor |
string (40) | Merchant name and location submitted to the card network. |
mcc |
string (4) | Merchant Category Code (e.g. 7995 = Betting). |
trace |
integer | Trace number linking all messages in the same transaction flow. |
terminal_id |
string (15) | Identifier for the terminal or merchant account that processed the payment. |
unique_tran_id |
string (36) | Gateway-generated UUID to uniquely identify the transaction (it can be blank). |
Successful response example:
<payment_authorizations_responses per_page=”100″ page=”1″ total_count=”2″ pages_count=”1″>
<payment_authorizations_response>
<xml_root>payment_authorization_response</xml_root>
<merchant_number>605000000002029</merchant_number>
<record_number>33202414090</record_number>
<card_number>465944******7359</card_number>
<exp_date/>
<currency>EUR</currency>
<amount>1234</amount>
<auth_code>15056</auth_code>
<auth_date>2019-06-10 16:17:18 UTC</auth_date>
<resp_code>Transaction approved</resp_code>
<reversed>N</reversed>
<pos_entry_mode>102</pos_entry_mode>
<voice>N</voice>
<avs_result/>
<cvv2_result>M</cvv2_result>
<card_type>M</card_type>
<ecom_type/>
<eci_sli>21</eci_sli>
<rrn>916116130233</rrn>
<card_acceptor>test.bg 12629314 BG</card_acceptor>
<mcc>7995</mcc>
<trace>1130233</trace>
<type/>
<card_sub_type/>
<terminal_id>53b1f5eacc9edd</terminal_id>
<unique_tran_id/>
</payment_authorizations_response>
<payment_authorizations_response>
<merchant_number>605000000002029</merchant_number>
<record_number>33202414090</record_number>
<card_number>465944******7359</card_number>
<exp_date/>
<currency>EUR</currency>
<amount>1234</amount>
<auth_code>15056</auth_code>
<auth_date>2019-06-10 16:17:18 UTC</auth_date>
<resp_code>Transaction approved</resp_code>
<reversed>N</reversed>
<pos_entry_mode>102</pos_entry_mode>
<voice>N</voice>
<avs_result/>
<cvv2_result>M</cvv2_result>
<card_type>M</card_type>
<ecom_type/>
<eci_sli>21</eci_sli>
<rrn>916116130233</rrn>
<card_acceptor>test.bg 12629314 BG</card_acceptor>
<mcc>7995</mcc>
<trace>1130233</trace>
<type/>
<card_sub_type/>
<terminal_id>53b1f5eacc9edd</terminal_id>
<unique_tran_id/>
</payment_authorizations_response>
</payment_authorizations_responses>
Troubleshooting and FAQ
HTTP code | Reason | Fix |
---|---|---|
400 | Malformed XML or missing required field. |
Check your XML matches the <payment_authorization_request> schema. |
401 | Invalid credentials. | Verify username / password or token. |
403 | IP not whitelisted. | Ask Support to add your IP range. |
500 | Gateway error. | Retry after a short delay; contact Support if the error persists. |