The only base URL for both environments is: https://api.korapay.com/

Test Mode: A sandbox environment for building and testing integrations without touching real money. It uses test API keys. All transactions are simulated.

Live Mode: The production environment for processing real transactions with actual money. It requires live API keys, which are only available after the merchant's account has been activated and KYC is complete.

Public Key: Prefixed pk_. It is used for client-side operations, primarily for initializing the Kora Checkout standard library on the frontend. It is safe to expose in client-side code. Please refer to our Reference Docs here to find the correct API keys required to authorize requests to each API.

Secret Key: Prefixed sk_. It is used for all server-side API calls. It must be kept confidential and stored securely on the server. Never expose the Secret Key in any client-side code. Please refer to our Reference Docs here to find the correct API keys required to authorize requests to each API.

The Secret Key must be passed as a Bearer token in the Authorization header of every server-side API request. Format: Authorization: Bearer sk_test_your_secret_key_here

Developers must use the Test Mode with their test API keys. Kora provides a set of test cards and specific bank account numbers (here) that can be used to simulate various transaction scenarios. For Checkout integrations, test payments can be made directly on the checkout modal. For API-based integrations, developers should use tools like Postman or write scripts to hit the sandbox API endpoints.

The full list of test cards for simulating successful payments, failed payments (e.g., insufficient funds), and 3D Secure authentication is available in the "Testing Your Integration" section of the developer documentation here.

Webhooks are the primary mechanism Kora uses to send real-time, asynchronous notifications to a merchant's server about events that happen on their account. This is crucial for events that are not instantaneous, such as the final success or failure of a bank transfer payment or the resolution of a chargeback. Merchants can rely on webhooks as the definitive source of truth for transaction status.

All webhook events follow a standard JSON structure like this:

JSON

{
"event": {
"type": "charge.success",
"id": "evt_123456789"
},
"data": {
// Object containing details of the event
// For charge.success, this will be the transaction object
},
"customer": {
// Customer object associated with the event
}
}

For additional webhook event samples, please refer to our API documentation here

This is critical. A developer must verify the webhook signature. Every webhook event sent by Kora includes a Kora-Signature header. The developer must compute their own signature using the received payload and their Secret Key (using an HMAC-SHA256 algorithm) and compare it to the signature in the header. If they don't match, the request should be rejected. This prevents processing of fraudulent webhook events not sent by Kora.

The server must respond with a 200 OK status code. Any other response code will be interpreted by Kora as a failure to deliver the webhook. Kora will attempt to resend a failed webhook multiple times with an exponential backoff strategy.

Error responses use standard HTTP status codes and a JSON body with a consistent structure:

JSON

{
"status": false,
"message": "A human-readable error message.",
"errors": {
"code": "ERROR_CODE_SLUG",
"message": "A more detailed error message.",
"attribute": "field_that_caused_the_error"
}
}

For more details on this, please refer to our documentation here and here. 

Answer: This is a common error indicating that the API request failed because some of the data provided was invalid or missing. The errors object will contain details about which specific field (attribute) caused the problem, for example, an invalid email format or a missing required currency.

Checkout - Standard: A JavaScript-based modal that pops up on the merchant's website. The merchant adds the Kora JS library to their site, and initiates the checkout with their Public Key and transaction details. The customer never leaves the merchant's site. For more details, please refer to our API documentation here. 

Checkout - Redirect: The merchant makes a server-side API call to generate a checkout_url. They then redirect their customer to this Kora-hosted payment page to complete the transaction. This is simpler and requires no frontend JavaScript integration. For more details, please refer to our API documentation here. 

POST - https://api.korapay.com/merchant/api/v1/charges/initialize

The request body must include amount, currency, customer details, and a redirect_url where the customer will be sent after the payment attempt.

Payment Links are shareable links for collecting payments, created from the Kora dashboard. They are a no-code solution. When a customer clicks the link, they are taken to a Kora-hosted page to complete the payment. This is ideal for merchants without a website or for collecting payments via social media or invoices.

POST - https://api.korapay.com/merchant/api/v1/virtual-bank-account

The request body requires a customer object containing at least the name and email of the customer for whom the account is being created. For more details, please refer to our API documentation here.

Through a webhook with the event type charge.success. The webhook payload will contain the full transaction object, including the amount paid and the customer details associated with that virtual account.

Underpayments: Kora's system will still fire a charge.success webhook with the amount that was actually paid. The merchant's business logic must then compare the amount_paid to the amount_expected and decide how to proceed (e.g., partially fulfill the order, contact the customer to pay the balance). For more details, please refer to our API documentation here. 

Overpayments: The same charge.success webhook is sent with the overpaid amount. The merchant's system should detect the surplus and decide how to handle it (e.g., credit the customer's wallet, process a partial refund for the excess amount). For more details, please refer to our API documentation here. 

The recommended method is Checkout (Standard or Redirect). In these flows, the sensitive card details are entered directly on Kora's secure elements, and the merchant's server never touches the raw card data. The merchant's server then receives a charge_reference after the customer completes the payment, which can be used to verify the transaction status.

This requires a higher level of PCI compliance. The process is typically:

Use a frontend library to tokenize the card details on the client-side.

Send the resulting token to the merchant's server.

The server makes a POST /charge/card request to the Kora API (https://api.korapay.com/merchant/api/v1/charges/card), including the token, amount, currency, and customer details.

Bank Transfer: A "push" payment. The customer must manually initiate the transfer from their bank app to a destination account provided by Kora.

Pay-with-bank: The customer’s bank usually requires the customer to authenticate the transaction before it can be completed. This authentication may be done using a one-time pin (OTP) sent to the customer, a payID generated through their banking app, or any other form of authentication set by the customer’s bank. With a successful authorization, authentication checks and sufficient balance a successful charge is made on the customer’s account.

POST - https://api.korapay.com/merchant/api/v1/charges/mobile-money

The request body must include the amount, currency (e.g., GHS, KES, XOF, XAF, TZS, EGP), customer details, mobile_number of the mobile money wallet, and other payment details as specified here. A prompt or OTP will typically be sent to the customer's phone to authorize the transaction.

Fetch all transactions: 

Pay-ins: 
GET - {{base_url}}/merchant/api/v1/pay-ins?limit=10

Payouts: 
GET - {{base_url}}/merchant/api/v1/payouts?limit=10

This supports pagination parameters like page and per_page.

Fetch a single transaction: 

Pay-ins:

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

Payouts: 
GET - https://api.korapay.com/merchant/api/v1/transactions/:transactionReference 

POST - https://api.korapay.com/merchant/api/v1/refunds/initiate

The request body requires the transaction_reference of the original charge you wish to refund. You can also specify an amount if you want to process a partial refund. If no amount is specified, a full refund will be initiated.

In the context of the Kora API, these terms are often used interchangeably to describe the process of sending money from the merchant's Kora wallet to an external destination, such as a customer's bank account.

POST - https://api.korapay.com/merchant/api/v1/transactions/disburse

The request body must include a destination object specifying the type (e.g., bank_account), amount, currency, and the recipient's details (e.g., account_number, bank_code).

POST - https://api.korapay.com/merchant/api/v1/transactions/disburse/bulk

The request body requires a payouts key, which is an array of payout objects. Each object in the array represents a single payout and contains the destination, amount, and currency for that specific recipient.

Yes, the documentation specifies a limit on the number of payouts that can be included in a single array. Please refer to the "Bulk Payouts via API" page for the exact current limit (e.g., 50 payouts per call). 

All test data required for simulating test transactions within the Sandbox environment is available here. 

To obtain the API keys, please follow these steps:

• Switch to test mode and navigate through Settings > API configuration to get the test API keys.
• Switch to live mode and navigate through Settings > API configuration to get the live API keys.

For a detailed guide on how this works, please watch the tutorial video below:

​https://www.youtube.com/watch?v=9C3PRejyxbE

To resend webhook notifications on the Kora (merchant) dashboard, follow these steps:

• Log in to your merchant dashboard.
• Search for the transaction ID (Payin/payout).
• Scroll down to 'Webhook/Metadata.'
• Click on 'Resend Webhook'.
  
  For a detailed guide on how this works, please watch the tutorial video below:

https://youtu.be/UQ-laVQOhiI

To whitelist the public IP address of the server used for payout requests on the Kora (Merchant) dashboard, follow these steps:

• Log in to your Kora(merchant) dashboard.
• Navigate through Settings > Security > IP Whitelisting.
• Enter the public IP address of your server.
• Click OK.

For a detailed guide on how this works, please watch the tutorial video below:

https://youtu.be/l65H22v0Sjw

• Go to “Settings” on the merchant dashboard.
• Click “API Configuration”.
• Under “Notification URL” at the bottom, you can set the URL.

For a detailed guide on how this works, please watch the tutorial video below:

https://youtu.be/9C3PRejyxbE