Overview

The Reconciliation API enables you to list transactions that you can use in your reconciliation process.

API endpoints

The API endpoints for the live and sandbox servers are:

API credentials

To use the Reconciliation API, you need the following credentials:

• clientId
• clientSecret
• merchantId

If you've integrated with Peach Payments using Embedded Checkout, Payment Links, Magento, or WooCommerce you can retrieve your credentials from the relevant page on the Peach Payments Dashboard. If you aren't using any of these products or can't find the credentials, contact support to request them.

Known limitations

The Reconciliation API has the following limitations:

• Rate limit: One request per second
• Date limit: Cannot query transactions before 1 January 2023
• Date range limit: Cannot query transactions on a date range longer than 24 hours per request

Quick links

📝 API playground Detailed reference to the Reconciliation API endpoint and mock calls. API reference	🚀 Postman collection Use the sample Reconciliation API calls in Postman. See the collection overview for more information.

API flows

Authentication flow

To use the Reconciliation API, you must retrieve your API credentials and then use them to get an access token from the Authentication API.

📘

The Authentication API endpoints are:

• Live: https://dashboard.peachpayments.com
• Sandbox: https://sandbox-dashboard.peachpayments.com

1. Make a POST https://dashboard.peachpayments.com/api/oauth/token request to the Authentication API with your client ID, client secret, and merchant ID to generate an access token.

   📘

   You can only use the access token to query the merchant whose credentials you used to generate the token. To query a different merchant, generate a new access token using that merchant's credentials.

   cURL

   curl --location --request POST '{peach-auth-service}/api/oauth/token'  
   --header 'content-type: application/json'  
   --data-raw  
   '{  
       "clientId": "{{clientId}}",  
       "clientSecret": "{{clientSecret}}",  
       "merchantId": "{{merchantId}}"  
   }'
   

2. The Authentication API responds with an access token.

   JSON

   {  
       "access_token": "<access token>",  
       "expires_in": "<token expiry duration in seconds>",  
       "token_type": "Bearer"  
   }
   

3. Make calls to the Reconciliation API with the access token in the authorisation header, for example, Authorization: Bearer {access_token}.

📘

• You can reuse the access token from step 2 for multiple API calls.
• When the token expires, you need to generate a new one.

See the Postman collection for more details on API authentication.

Code snippet

async function authenticate(clientId, clientSecret, merchantId) {
  let response = await fetch("<peach auth service>/api/oauth/token", {
    method: "POST",
    body: JSON.stringify({
      clientId,
      clientSecret,
      merchantId
    })
  });

  if (response.ok) {
    let body = await response.json();

    return body.access_token;
  } else {
    throw new Error("Unable to authenticate");
  }
}

async function getTransactionsForRecon(token, merchantId, startDate, endDate) {
  let response = await fetch("<payment links api>/api/merchants/" + merchantId + "/transactions-recon?startDate=" + startDate + "&endDate=" + endDate, {
    headers: new Headers({
      "Authorization": "bearer " + token
    })
  });

  if (response.ok) {
    return await response.json();
  } else {
    throw new Error("Unable to retrieve Transactions details");
  }
}

let bearerToken = await authenticate(clientId, clientSecret, merchantId);

let transactions = await getTransactionsForRecon(bearerToken, merchantId, "2024-04-01T00:00:00.000Z", "2024-04-02T00:00:00.000Z");

List transactions reconciliation flow

The list transactions reconciliation flow enables you to retrieve a list of transactions with their metadata.

🚧

The Reconciliation API has various limitations.

1. The merchant sends a list transactions reconciliation request to the Reconciliation API.
2. The Reconciliation API responds with a list of transactions and their metadata.

Example requests and responses

For sample requests and responses, see the interactive API playground or use the Peach Payments Postman collection: