Reconciliation

Reconciling transactions within the Payen platform relies on the merchantRef field provided by the merchant when making any API requests. This field should be unique to the merchant, and will be a searchable field in the Vision portal and also appear in reports to identify the transaction.

Transactions can have subsequent operations, such as credits, that reference an original authorisation transaction. This can create confusion when trying to reconcile, due the fact they all have the same merchantRef. The merchantRef field is designed to only identify the transaction, not the operations within it. To mitigate this, we can return a field in the response called operationRef that will uniquely identify each operation. This reference will be a searchable field in the Vision portal and also appears in reports to identify the operation.

warning

The operationRef field will be available soon. For more information on this feature, please speak to your Integration Manager.

Example API Response

A merchant sends an authorisation request and provides a merchantRef with value "xkP0poGyDYiDJ12". An example successful response is shown below with the merchantRef and the operationRef values highlighted.

The operationRef appears in 2 places:

1. In the status section, which indicates the operationRef for the current API request/response.
2. In the paymentHistory section. Each paymentAttempt within a transaction will include it's operationRef. Over the life cycle of a transaction, multiple operations may be created, such as refunds and credits, each with their own operationRef.

JSON

Authorisation Response highlighting key references

   {
      "version": 2,
      "type": "AUTH_CAP",
      "customerId": "1765277404605",
      "merchant": {
         "merchantId": "1000011",
         "accountId": "2000040"
      },
      "transaction": {
         "amount": "1000",
         "currency": "GBP",
         "merchantRef": "xkP0poGyDYiDJ12",
         "gatewayRef": "da30e275-161a-4942-9949-838ed1f8eb93",
         "transactionType": "ECOMMERCE"
      },
      "status": {
         "code": "SUCCESS",
         "message": "Operation successful",
         "timestamp": "2025-12-09T10:50:05.000Z",
         "operationRef": "01K59QF7Z74G51STE8H8A84C2J"
      },
      "paymentHistory": {
         "paymentAttempt": [
            {
               "order": 1,
               "timestamp": "2025-12-09T10:50:05.000Z",
               "code": "SUCCESS",
               "operationRef": "01K59QF7Z74G51STE8H8A84C2J",
               "amount": 1000,
               "currency": "GBP",
               "paymentMethodType": "CARD",
               "token": "c4804efc867743b39815b6c59c83b36e",
               "cardResponse": {
                  "acquirerRef": "Test AcquirerRef",
                  "validDate": "042011",
                  "expiryDate": "042030",
                  "cardBin": "400001",
                  "cardLastFour": "3227",
                  "cardIssuingBank": "Test Issuing Bank",
                  "cardIssuingCountry": "USA",
                  "cardType": "VISA_CREDIT",
                  "authCode": "86394",
                  "cvv": "MATCHED",
                  "avsAddress": "NOT_CHECKED",
                  "avsPostcode": "NOT_CHECKED",
                  "bankMid": "123456",
                  "iso8583code": "00"
               }
            }
         ]
      }
   }

XML

Authorisation Response highlighting key references

  <paymentResponse>
     <version>2</version>
     <type>AUTH_CAP</type>
     <customerId>1765277393683</customerId>
     <merchant>
        <merchantId>1000011</merchantId>
        <accountId>2000040</accountId>
     </merchant>
     <transaction>
        <amount>1000</amount>
        <currency>GBP</currency>
        <merchantRef>hu1SPRUF3o8Lg8w</merchantRef>
        <gatewayRef>18ebc196-1677-4042-8ffb-754cb33d3b8a</gatewayRef>
        <transactionType>ECOMMERCE</transactionType>
     </transaction>
     <status>
        <code>SUCCESS</code>
        <message>Operation successful</message>
        <timestamp>2025-12-09T10:49:55.000Z</timestamp>
        <operationRef>01K59QF7Z74G51STE8H8A84C2J</operationRef>
     </status>
     <paymentHistory>
        <paymentAttempt>
           <order>1</order>
           <timestamp>2025-12-09T10:49:55.000Z</timestamp>
           <code>SUCCESS</code>
           <operationRef>01K59QF7Z74G51STE8H8A84C2J</operationRef>
           <amount>1000</amount>
           <currency>GBP</currency>
           <paymentMethodType>CARD</paymentMethodType>
           <token>8b794788f6614acfbdd5f41b4691f3a6</token>
           <cardResponse>
              <acquirerRef>Test AcquirerRef</acquirerRef>
              <validDate>042011</validDate>
              <expiryDate>042030</expiryDate>
              <cardBin>400001</cardBin>
              <cardLastFour>1526</cardLastFour>
              <cardIssuingBank>Test Issuing Bank</cardIssuingBank>
              <cardIssuingCountry>USA</cardIssuingCountry>
              <cardType>VISA_CREDIT</cardType>
              <authCode>81742</authCode>
              <cvv>MATCHED</cvv>
              <avsAddress>NOT_CHECKED</avsAddress>
              <avsPostcode>NOT_CHECKED</avsPostcode>
              <bankMid>123456</bankMid>
              <iso8583code>00</iso8583code>
           </cardResponse>
        </paymentAttempt>
     </paymentHistory>
  </paymentResponse>

Example Report

The example report below shows the content of a Settlement Summary CSV file, with columns hidden for brevity. The important aspects are that both the merchantRef and operationRef values are displayed in the Merchant Transaction Ref and Operation Ref columns respectively.

The merchantRef and operationRef returned in the API response can be matched to records in reports to reconcile activity.