Reconciliation API
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:
Service | Live | Sandbox |
---|---|---|
Authentication | https://dashboard.peachpayments.com | https://sandbox-dashboard.peachpayments.com |
Reconciliation | https://reconciliation.peachpayments.com | https://sandbox-reconciliation.ppay.io |
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
Authentication flow.
-
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 --location --request POST '{peach-auth-service}/api/oauth/token' --header 'content-type: application/json' --data-raw '{ "clientId": "{{clientId}}", "clientSecret": "{{clientSecret}}", "merchantId": "{{merchantId}}" }'
-
The Authentication API responds with an access token.
{ "access_token": "<access token>", "expires_in": "<token expiry duration in seconds>", "token_type": "Bearer" }
-
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({
"Authentication": "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.
List transactions reconciliation flow.
- The merchant sends a list transactions reconciliation request to the Reconciliation API.
- 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:
Updated 3 months ago