developers.korapay.com APIdevelopers.korapay.com ↗
Access Korapay's payments platform via API: initialize checkouts, manage virtual bank accounts and cards, initiate payouts, verify Nigerian bank accounts, and check balances.
curl -X POST 'https://api.parse.bot/scraper/fc546151-f312-4733-88a5-e8d1e9aa51bd/initialize_checkout' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{}'Initialize a checkout/charge session to get a redirect URL for payment.
| Param | Type | Description |
|---|---|---|
| amountrequired | number | Amount to charge |
| currency | string | Currency code (e.g., NGN, GHS, KES) |
| narration | string | Transaction description |
| referencerequired | string | Unique transaction reference |
| redirect_urlrequired | string | URL to redirect the customer to after payment |
| customer_namerequired | string | Customer's name |
| customer_emailrequired | string | Customer's email address |
| notification_url | string | Webhook URL for payment notifications |
{
"type": "object",
"fields": {
"data": "object",
"status": "boolean",
"message": "string"
},
"sample": {
"data": {
"reference": "test-postman-transaction-1",
"checkout_url": "https://checkout.korapay.com/6000/test-postman-transaction-1"
},
"status": true,
"message": "Charge initialized successfully"
}
}About the developers.korapay.com API
The Korapay API exposes 10 endpoints covering the full payments lifecycle on the Korapay platform, from initializing a checkout session with initialize_checkout to verifying Nigerian bank account details and issuing virtual cards. Each endpoint returns a consistent envelope with a status boolean, a message string, and a data object or array carrying the transaction or account payload. Developers can manage pay-ins, pay-outs, virtual bank accounts, and real-time balance queries in a single integration.
Checkout and Pay-In Management
The initialize_checkout endpoint accepts a required amount, reference, redirect_url, customer_name, and customer_email, returning a data object that includes the redirect URL your UI hands to the customer. Once payment is attempted, query_charge takes a reference and returns the current status and transaction details. To review historical inflows, get_all_pay_ins supports date-range filtering via from and to (YYYY-MM-DD), pagination via page and limit, and filtering by status (e.g., success, failed) or currency.
Virtual Bank Accounts and Cards
create_virtual_bank_account provisions a virtual account for a customer identified by account_reference, customer_email, and account_name. The permanent boolean controls whether the account persists or is one-time use; a BVN (kyc_bvn) is required by some issuing banks. query_virtual_bank_account retrieves the account details by account_reference. For card issuance, create_virtual_card issues a new card given an amount, reference, card_holder_reference, and optional brand (e.g., visa, mastercard) and currency.
Payouts and Bank Verification
initiate_payout handles disbursements to both Nigerian bank accounts and mobile money wallets. Bank payouts require bank_code; mobile money payouts require mobile_number and operator (e.g., safaricom-ke). query_payout fetches the current state of a disbursement by its reference. verify_bank_account resolves a 10-digit account number against a Nigerian bank code and returns bank_name, bank_code, account_number, and account_name — useful for validating recipient details before initiating a payout.
Balances
get_balances takes no inputs and returns the authenticated account's real-time available and pending balances inside a data object, giving a live snapshot of funds across currencies held in the account.
- Generate a checkout redirect URL and poll for completion status using
initialize_checkoutandquery_charge. - Provision permanent virtual bank accounts for customers and route incoming transfers automatically via
create_virtual_bank_account. - Validate a recipient's Nigerian bank account name before disbursing funds with
verify_bank_account. - Disburse salaries or vendor payments to mobile money wallets across East Africa via
initiate_payoutwith an operator slug. - Issue branded virtual Visa or Mastercard cards to users for expense management using
create_virtual_card. - Audit inflow history by date range and status using
get_all_pay_inswithfrom,to, andstatusfilters. - Monitor live account balances across currencies before triggering bulk payouts with
get_balances.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Korapay have an official developer API?+
What does `verify_bank_account` return, and which countries does it cover?+
data object containing bank_name, bank_code, account_number, and account_name for the resolved account holder. Currently only Nigerian (NGN) bank accounts are supported via Nigerian bank codes such as 044 (Access Bank) or 011 (First Bank).Can I retrieve transaction history for payouts the way I can for pay-ins?+
get_all_pay_ins with date, currency, status, and pagination filters, but there is no equivalent bulk-listing endpoint for payout history — individual payouts are queried one at a time via query_payout. You can fork this API on Parse and revise it to add a payout-listing endpoint if one becomes available on the platform.Does the API support currencies other than NGN?+
currency parameter and the documentation references GHS and KES alongside NGN for checkout and payout flows. However, verify_bank_account currently supports only NGN. Mobile money payouts use an operator slug (e.g., safaricom-ke) rather than a currency filter. You can fork the API on Parse and revise it to expose additional currency-specific filtering as Korapay expands coverage.How does `get_all_pay_ins` handle pagination?+
page and an integer limit as query parameters. The endpoint returns a data array sized to limit for the requested page. If neither is specified, the API returns a default page of results. There is no cursor-based pagination; iteration is strictly offset-based via page.