search icon
close icon close icon

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).
* Either 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.