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.

Currency Code

Country

Available Payment Methods

GHS

🇬🇭 Ghana

  • GIP Instant Transfer (Preferred)
  • ACH Next Day Payment - Settled by 10:00AM the following day
  • Mobile Money

KES

🇰🇪 Kenya

  • Instant Transfer

XAF

🇨🇲 Cameroon

  • Instant Transfer

Here are the request parameters for the endpoint:

ParameterTypeRequiredDescription
customer_nameStringTrueThe full name of the customer.
customer_emailStringTrueThe email address of the customer.
currencyStringTrueThe currency code for the transaction

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

Pool Accounts
  1. Enter the required customer details.
  2. A new Reference ID will be generated instantly and displayed on your dashboard.

Generate Pool Account

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"
        }
    }
}
Generation Error

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:

ParameterTypeRequiredDescription
referenceStringTrueThis is the payment reference sent in the webhook notification

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"
       }
   }
}

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