Payout API
Payouts on Korapay are done using our RESTful APIs, enabling a smooth, solid integration.
If a payout request is triggered, Korapay will directly disburse from your positive balance, and notify your application via an API callback when the transfer has been completed.
Furthermore, you can always get the status of a single payout at any time via API or monitor the transaction status on the dashboard, where you can also see the payment details with a reference number for the transaction.
Use Case
Let's consider a typical case where your service uses a company eWallet to pay customers, employees, etc.
On your website when a customer requests a payout to their bank account. Your website’s backend asks Korapay to process this payout. Korapay processes the payment to the customer’s bank account, then notifies your website’s backend when the payout has been completed. Easy peasy!
Let's take a quick look at how you'll use the Korapay API to implement the workflow for this use case. First, we'll look at your high-level workflow. Then we'll explain how to implement the workflow in detail. We'll use a sample code to bring the workflow to life.
Workflow - Payout to customer’s bank account
This is what the workflow would look like from a birds-eye view.
Stage 1 - Requesting a Payout

- On your website, a payout request is made by a customer.
- Your website backend asks Korapay to process the payout.
Stage 2 - Processing the Payout

- Korapay processes the payout.
- The customer's bank account is credited with funds from the merchant’s eWallet.
- Your Korapay dashboard or application is notified that the money was credited to the bank account
Implementing the Payout Workflow
Now, let’s dive deeper into how this workflow would be implemented end-to-end.
Step 1 - Use List banks API to get valid bank codes.
Step 2 - Verify the destination bank account - Optional
Step 3 - Request payout
Step 4 - Receive confirmation via webhook when the payout is completed
Step 5 - Query the transaction to get the status of the transaction.
Before you start:
Make sure to check out Quick Start learn more about Test and Live Modes, as well as API keys and how to use them.
1 - Find bank codes from List Banks
For a successful payout, you need to input the destination bank of the transaction in the bank field. This means you need to get details of the direct bank for that beneficiary (eg., Access Bank, or Wema Bank).
In this example, you'll find the different bank types that allow transfers in the currencies that we support.
Request Banks Type (Nigeria)
Request for a list of all available bank codes for transfers in Nigeria.
{{baseurl}}/merchant/api/v1/misc/banks?countryCode=NG
Banks Type response
This is an example response to the request for bank type
{
"status": true,
"message": "success",
"data": [
{
"name": " Bank name", // e.g Access Bank Nigeria
"slug": " Bank slug", // e.g access
"code": " Bank code", // e.g 044
"country": "NG"
},
]
}
Request Banks Type (Kenya)
Request for a list of all available bank codes for transfers in Kenya.
{{baseurl}}/merchant/api/v1/misc/banks?countryCode=KE
Banks Type response
This is an example response to the request for bank type
{
"status": true,
"message": "success",
"data": [
{
"name": "ABC Bank", // e.g ABC Bank Kenya
"slug": " Bank slug", // e.g abc-bank-ke
"code": " Bank code", // e.g 0035
"country": "KE"
},
]
}
2 - Verify the destination bank account - Optional
Use Verification to resolve the bank account before you request the payout. See the Verification request and response below.
Bank Account Resolve request
This resolves the bank account:
{{baseurl}}/merchant/api/v1/misc/banks/resolve
Request body
You asked Korapay to resolve the bank account. For that, you'll use Bank Account Resolve with the following parameters.
Field | Data Type | Description |
---|---|---|
bank | String | Required - bank code of account number |
account | String | Required - account number to be resolved |
currency | String | Required - country currency |
Bank Account Resolve response
Here’s how the response should look like.
{
"status": true,
"message": "Request Completed",
"data": {
"bank_name": "United Bank for Africa",
"bank_code": "033",
"account_number": "2158634852",
"account_name": "EBUKA CIROMA OLADEMJI"
}
}
3 - Request Payout
For this, you'll use the Payout API.
Payout Request
{{baseurl}}/merchant/api/v1/transactions/disburse
You need to find the required field for each payout request.
Field | Data Type | Description |
---|---|---|
reference | String | Required - unique transaction reference |
destination | Object | Required |
destination.type | String | Required - can be bank_account or mobile_money |
destination.amount | Number | Required - transaction amount in two decimal places. |
destination.currency | String | Required - transaction amount currency e.g. NGN, KES. |
destination.narration | String | Optional - transaction narration or description |
destination.bank_account | Object | Required - if destination type is bank_account |
destination.bank_account.bank | String | Required - recipient bank code. Some bank codes that you can use to simulate successful transactions in Test mode are 044, 033, 058 (i.e.for Access Bank, UBA and GTCO respectively). See the bank details for other test scenarios here. |
destination.bank_account.account | String | Required - recipient account number |
destination.mobile_money | Object | Required - if destination type is mobile_money |
destination.mobile_money.operator | String | Required - if destination.type is mobile_money , the mobile money operator slug, eg. safaricom-ke . |
destination.mobile_money.mobile_number | String | Required - if destination.type is mobile_money , the mobile number attached to the mobile money account. |
destination.customer | Object | Required |
destination.customer.name | String | Optional - Customer Name |
destination.customer.email | String | Required - Customer Email |
metadata | Object | Optional - It takes a JSON object with a maximum of 5 fields/keys. Empty JSON objects are not allowed. Each field name has a maximum length of 20 characters. Allowed characters: A-Z , a-z , 0-9 , and - . |
Payout Response
Here’s how the response for your payout request should look like:
{
"status": true,
"message": "transfer initiated successfully",
"data": {
"amount": "100.00",
"fee": "2.50",
"currency": "NGN",
"status": "processing",
"reference": "KPY-D-t74azVrw9oPLtv9",
"narration": "Test Transfer Payment",
"message": "Payout processing",
"customer": {
"name": "John Doe",
"email": "[email protected]",
"phone": null
},
"metadata": {
"internalRef": "JD-12-67",
"age": 15,
"fixed": true,
}
}
}
4 - Receive confirmation via webhook
You can set your application to receive a confirmation via webhooks when the payout is completed. Please visit Webhooks to see more information about the webhook request body and how to verify and handle the webhook request.
Updated 9 months ago