Pool Accounts

🚧

Beta Disclaimer

Please note that this service is currently only available to merchants participating in our beta program. If you have any feedback or questions, please contact us.

Pool Accounts are a special type of payment solution that enable you to receive local payments efficiently through bank accounts. Instead of generating a unique virtual bank account for every customer, you generate and assign a unique Reference ID to each customer.

💡 Note: It is important to note that all customer payments are made into a single bank account. However, each payment is uniquely identified and differentiated using the Reference ID provided for that customer or transaction.

Customers make payments directly into a shared pool account using their assigned Reference ID in the payment narration. Because the Reference ID is unique to the customer and required in the payment narration, this process enables automatic tagging and tracing of each transaction back to the correct customer — ensuring clear identification, simplified reconciliation, and accurate settlements to your account.

Whether you're managing hundreds or thousands of customers, Kora’s Pool Account solution simplifies how you track who paid what.

Benefits of Pool Accounts

With Pool Accounts, you can:

• Get paid locally across supported African countries.
• Assign unique Reference IDs to each customer or transaction for easy tracking.
• Stay updated with real-time notifications when funds are settled to your position.
• Simplify your reconciliation with easy access to downloadable transaction and settlement history.

How to accept payments with Pool Accounts

You can start accepting payments from your customers with Pool Accounts in three (3) steps:

1. Generate a Reference ID
   To generate a Reference ID, make a request to the Create Reference API. The response will contain the Reference ID and associated account details needed to complete the payment lifecycle.
2. Set up webhooks
   Configure your webhook endpoint to receive real-time notifications when payments are made and settled. You can also monitor and filter transaction activity from your dashboard for full visibility.
3. Verify payment
   After you receive a webhook notification from us, verify the payment by making a request to our Transaction Query API.

Generating a Reference ID

To create a Pool Account Reference ID, you’ll need to make a request to the Create Reference API endpoint.

{{baseurl}}/api/v1/pool_accounts

You can generate a reference ID for any of the countries listed below. To generate a reference for a specific country, the currency code (as shown below) must be passed in the currency field as seen below.

Here are the request parameters for the endpoint:

Here's what a response could look like:

{
    "status": true,
    "message": "Pool account reference has been created successfully",
    "data": {
        "reference": "DEMKP12345689KES",
        "customer_name": "test1",
        "customer_email": "[email protected]",
        "currency": "KES",
        "date_created": "2025-08-05T10:08:39.967Z",
        "account_details": {
            "currency": "KES",
            "bank_code": "1234567890",
            "bank_name": "Kora KES Bank",
            "swift_code": "KORABANK123",
            "account_name": "Kora Technologies Ltd",
            "account_number": "1234567890",
            "branch_address": "123 Kora Street, City, Country"
        }
    }
}
}

💡 The Reference ID will usually have the following format below:
{MerchantPrefix} + KP + {RandomAlphaNumeric} + {Currency}

You can also generate a Reference ID directly from the Merchant Dashboard. To do that, simply follow these steps:

1. Log in to your Merchant Dashboard.
2. Navigate to the Accounts tab on the side menu.
3. Click on the Account dropdown on the page and select 'Pool Accounts'.
4. On the Pool Accounts page, click on "Generate Reference".

5. Enter the required customer details.
6. A new Reference ID will be generated instantly and displayed on your dashboard.

Share the Reference ID with Your Customer

Once a Reference ID has been generated, you must share it with the customer along with the corresponding bank account details provided to you. The customer is required to include the exact Reference ID in the payment narration or description field to ensure accurate tracking and successful reconciliation.

💡

Only one Reference ID can be generated per customer email address.

If you attempt to generate another Reference ID with an email address that has already been assigned to an existing Reference ID, you'll receive the following error response payload:

{
    "status": false,
    "message": "A reference already exists for this customer",
    "data": {
        "reference": "DEMKP12345689KES",
        "customer_name": "John Dore",
        "customer_email": "[email protected]",
        "currency": "KES",
        "date_created": "2025-08-05T10:08:39.000Z",
        "account_details": {
            "currency": "KES",
            "bank_code": "1234567890",
            "bank_name": "Kora KES Bank",
            "swift_code": "KORABANK123",
            "account_name": "Kora Technologies Ltd",
            "account_number": "1234567890",
            "branch_address": "123 Kora Street, City, Country"
        }
    }
}

Getting notified of the payment

After payment has been made into a Pool Account with the associated Reference ID, we send a webhook notification to your webhook notification URL. The reference in the notification payload can be used to get the details of the payment.

You can read more about how to handle webhook notifications here.

Here's a sample webhook notification:

{
  "event": "charge.success",
  "data": {
    "fee": 0,
    "amount": 200,
    "status": "success",
    "currency": "NGN",
    "reference": "KPY-PAY-47AgdDKFMklhVSg",
    "payment_method": "pool_account",
    "payment_reference": "KPY-PAY-47AgdDKFMklhVSg",
    "pool_account_reference": "DEMKP12345689GHS"
  }
}

Getting the details of the payment made to the Pool Account

All the payments that have been made to a Pool Account can be retrieved by making a GET request to the Transaction Query API endpoint.

https://api.korapay.com/merchant/api/v1/charges/:reference

The request parameters for this endpoint are:

And, the response to the request could look like this:

{
   "status": true,
   "message": "Charge retrieved successfully",
   "data": {
       "reference": "KPY-PAY-47AgdDKFMklhVSg",
       "status": "success",
       "amount": "200.00",
       "amount_paid": "200.00",
       "fee": 0,
       "currency": "GHS",
       "description": "Pool account transfer from John Doe",
       "customer": {
           "name": "John Doe",
           "email": "[email protected]"
       },
       "pool_account": {
           "pool_account_reference": "DEMKP12345689GHS"
       }
   }
}

Error Codes

The following error codes may be returned by the API:

API Statuses and Description Reference

Support

Need help with using Pool Accounts? Reach out to [email protected]
(Please include the Pool Account Reference ID and transaction details in your request for faster resolution.)