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 if you don't have API credentials available, click Create API credentials. Note your client ID, client secret, and merchant ID.

📘

• 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 bank account verification request flow

The create bank account verification request flow enables you check whether a bank account is valid and can receive funds. By verifying accounts before attempting to pay out to them, you can reduce invalid account, check digit verification, and other errors. This results in less time spent investigating failed payouts and lower costs.

📘

See the overview for the list of banks that the bank account verification feature supports.

🚧

When executing a bank verification request, keep in mind the known limitations.

After making the bank account verification request, the system sends the result via a webhook. You can also use the Query bank verification result call to check the result.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#EE8031', 'loopTextColor': '#EE8031', 'textColor':'#EE8031', 'fontFamily': 'Inter' }}}%%
sequenceDiagram
autonumber
participant Merchant
participant Payouts API
Merchant->>Payouts API: Bank account verification request
Payouts API-->>Merchant: Response with verification ID
Payouts API->>Merchant: Webhook notification with verification ID and result
Merchant-->>Payouts API: Response (HTTP 200 (Result code, Result description))
alt Poll
    Merchant->>Payouts API: Query bank verification result request
    Payouts API-->>Merchant: Response with verification result
end

1. The merchant sends a create bank account verification request to the Payouts API.
2. The Payouts API responds with a verification ID.
3. The Payouts API sends a webhook notification with the verification result.
4. The merchant returns a 200 status code response acknowledging the webhook.
5. If the merchant wants to, they can execute the query bank verification result call to get the result, if it is available.
6. The Payouts API responds with the verification result.

🚧

To receive the webhook with the final result, you must have added a bank account verification webhook in the Dashboard.

Query bank verification result flow

If you haven't configured a webhook endpoint or don't want to wait for the webhook to arrive, you can also execute the query bank verification result call to check the verification result.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#EE8031', 'loopTextColor': '#EE8031', 'textColor':'#EE8031', 'fontFamily': 'Inter' }}}%%
sequenceDiagram
autonumber
participant Merchant
participant Payouts API
Merchant->>Payouts API: Query bank verification result request
Payouts API-->>Merchant: Response with verification result

1. Execute the query bank verification result call to get the result of a create bank account verification request.
2. The Payouts API responds with the verification result.

Create payout request flow

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

Use one create payout request API call to pay multiple customers by including all the customer details in the payouts array as described in the API reference. Do not use a create payout request to pay a single customer unless you only have to pay one customer.

To see an example of a create payout request with multiple recipients, go to the API reference section and view the cURL request section on the right.

🚧

When creating payouts, keep in mind the known limitations.

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

For payouts, 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.

For bank account verification, Peach Payments sends a webhook with the bank account verification result.

1. The Payouts API sends a webhook with the payout status or with the bank account verification result.

   📘

   To verify Payouts webhooks, you require the signing secret which you can request from Peach Payments support. You can verify the webhook's signature in two ways, using the webhook-id and webhook-timestamp parameters that you receive in the webhook header:

   • Using Svix libraries
   • Manually

2. The merchant returns a 200 status code response acknowledging the webhook.

Webhook configuration

Follow these instructions to add a webhook for Payouts or bank account verification using the Peach Payments Dashboard.

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.

Payouts

Peach Payments sends webhooks for the following payout events:

• Processing
• Successful
• Failed

📘

See the API reference for more details on the payout status update webhook.

The webhook payload resembles the following:

{
  "status": "processing",
  "payoutId": "d3e31e2d-4f50-49f7-b89f-fd3f0b3642bb",
  "lastUpdated": "2025-07-02T11:00:04.352Z",
  "resultCode": "2900.000.003"
}

{
  "status": "successful",
  "payoutId": "ae3be0f1-40d1-4b28-8072-6f78d4493444",
  "lastUpdated": "2025-07-02T11:00:45.406Z",
  "resultCode": "2000.000.000"
}

{
  "status": "failed",
  "payoutId": "30ce5525-7de5-492d-a147-15592b14b266",
  "lastUpdated": "2025-07-02T11:00:04.566Z",
  "resultCode": "2001.002.106",
  "error": {
    "title": "Payout processing error",
    "message": "There is no account associated with the account number and the bank you entered. Double-check your input and try again.",
    "code": "2001.002.106"
  }
}

Bank account verification

See the API reference for more details on the bank account verification update webhook.

To see an example webhook payload, go to the API reference and view the PAYLOAD section on the right.

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.

Sample requests and responses

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