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

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

Stage 2 - Processing the Payout

1. Korapay processes the payout.
2. The customer's bank account is credited with funds from the merchant’s eWallet.
3. 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.

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.

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.