Overview

The Payouts API enables you to make instant EFT payments to suppliers, employees, partners, or customers. It also allows you to check the status of your payouts and to retrieve your balance.

API endpoints

The following are the API endpoints for the live and sandbox servers:

API credentials

Follow these steps to find your credentials:

1. Log in to the Peach Payments Dashboard.
2. In the left navigation menu, click Payouts.
3. Select the Settings tab and note your client ID, client secret, and merchant ID.

🚧

If you don't have access to the Payouts section or can't find your credentials, contact support.

📘

• To retrieve your sandbox credentials, switch to the sandbox Dashboard and follow the instructions above.
• If someone compromises your credentials, use the Regenerate client ID and client secret option to create new API credentials.

API flows

Authentication flow

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

📘

The Authentication API endpoint is available in the API endpoints section.

1. Make a POST {peach-auth-service}/api/oauth/token request to the Authentication API with your client ID, client secret, and merchant ID to generate an access token.

   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 Payouts 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.

Create payout request flow

The create payout request flow enables you create a payout to pay multiple customers.

1. The merchant sends a create payout request to the Payouts API.
2. The Payouts API responds with a request ID and multiple payout IDs.
3. The Payouts API pays a customer.
4. The Payouts API sends a webhook notification for each payout.
5. The merchant returns a 200 status code response acknowledging the webhook.
6. If there are issues with the request or the customers bank accounts, payouts could fail.
7. The Payouts API sends a webhook notification for each failed payout.
8. The merchant returns a 200 status code response acknowledging the webhook.

List payout requests flow

The list payout requests flow enables you to view all your payouts and payout requests.

1. The merchant sends a list payout requests call to the Payouts API.
2. The Payouts API responds with the payouts.

Query payout request flow

The query payout request flow enables you to query the status of the payouts.

1. The merchant sends a query payout request to the Payouts API.
2. The Payouts API responds with the statuses of all the payouts in the request.

Retrieve your balance and last transaction date flow

The retrieve your balance and last transaction date flow enables you to retrieve your balance as well as the date of your last payout.

1. The merchant sends a request to retrieve their balance and last transaction date to the Payouts API.
2. The Payouts API responds with the merchant's balance and the date of their last transaction.

Download payouts transaction report flow

The download payouts transaction report flow enables you to download a CSV file containing all your payouts for the specified period.

1. The merchant sends a download payouts transaction report call to the Payouts API.
2. The Payouts API responds with the payouts transaction report CSV.

Download payouts statement report flow

The download payouts statement report flow enables you to download a CSV file containing your statement for the specified period.

1. The merchant sends a download payouts statement report call to the Payouts API.
2. The Payouts API responds with the payouts statement report CSV.

Webhook flow

Webhooks provide updates on any changes in the state of the payouts. The Payouts API sends them regardless of whether the payout succeeded or failed.

1. The Payouts API sends a webhook with the payout status.
2. The merchant returns a 200 status code response acknowledging the webhook.

Webhook configuration

To configure a webhook, provide Peach Payments support with your webhook URL, ensuring that your system responds with a 200 status response. Peach Payments sends two webhooks to this URL, the first without data (curl -v -X POST https://www.mysite.co.za/pp-hosted/secure/webhook) and the second with JSON data (curl -v -H "Content-Type: application/json" -X POST -d '{"test":true}' https://www.mysite.co.za/pp-hosted/secure/webhook) if the initial attempt fails. If both attempts fail to return a 200 status, Peach Payments considers the validation unsuccessful.

If you use IP allowlisting for webhooks, ensure that your allowlist includes the Peach Payments IPs to ensure that Peach Payments can send you webhooks.

Webhook events

When your service receives a webhook notification, it must return a 200 HTTP status code. Peach Payments sends notifications using the URL-encoded query string format via HTTP POST. If your service does not return a 200 HTTP status code, the webhook service considers the notification delivery as failed and retries sending the notification later.

Peach Payments sends webhooks for the following events:

• Processing
• Successful
• Failed

After decryption, the webhook payload resembles the following:

{
  "status": "processing",
  "payoutId": "84920878-fc32-494f-8e30-6a2465c9a456",
  "lastUpdated": "2024-03-14T22:00:00.000Z"
}

{
  "status": "successful",
  "payoutId": "84920878-fc32-494f-8e30-6a2465c9a456",
  "lastUpdated": "2024-03-14T22:01:00.000Z"
}

{
  "status": "failed",
  "payoutId": "84920878-fc32-494f-8e30-6a2465c9a455",
  "lastUpdated": "2024-03-14T22:11:00.000Z"
}

Webhook retry mechanism

Peach Payments expects a 200 HTTP for successful webhook delivery and a non-200 HTTP status code for failures.

For an unsuccessful response, Peach Payments retries the webhook for 30 days or until a successful acknowledgement (200 HTTP) occurs.

Peach Payments uses exponential backoff logic for retries, with the interval between retries being:

• 1 minute
• 2 minutes
• 4 minutes
• 8 minutes
• 15 minutes
• 30 minutes
• 1 hour
• Every day until 30 days have passed since the first attempt

For example, for an attempt that fails three times before succeeding, Peach Payments delivers the webhook 15 minutes after the first attempt.

If you request that Peach Payments disable your endpoint, Peach Payments disables delivery attempts to the endpoint as well.

Example requests and responses

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