Korapay APIdevelopers.korapay.com ↗
Access Korapay's payment infrastructure: initialize checkouts, verify Nigerian bank accounts, manage virtual accounts and cards, and query payouts via one API.
What is the Korapay API?
This API exposes 10 endpoints covering Korapay's core payment infrastructure, including initialize_checkout for generating redirect-based payment sessions, verify_bank_account for resolving Nigerian bank account holder names, virtual bank account creation, payout initiation, and real-time balance retrieval. Response shapes return structured fields including account_name, bank_name, transaction status, and reference across both collection and disbursement flows.
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 '{}'Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace developers-korapay-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Korapay Bank Verification SDK — verify Nigerian bank accounts."""
from parse_apis.korapay_bank_verification_api import Korapay, BankCode, Currency, AccountNotFound
korapay = Korapay()
# Verify a bank account at Access Bank using the typed enum
account = korapay.bankaccounts.verify(
bank_code=BankCode.ACCESS_BANK,
account_number="0690000032",
currency=Currency.NGN,
)
print(account.bank_name, account.account_name, account.account_number)
# Verify another account at a different bank
try:
gtb_account = korapay.bankaccounts.verify(
bank_code=BankCode.GTBANK,
account_number="0123456789",
)
print(gtb_account.bank_name, gtb_account.account_name)
except AccountNotFound as exc:
print(f"Account not found: {exc}")
print("exercised: bankaccounts.verify with BankCode enum, Currency enum, and AccountNotFound error handling")
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 Korapay API
Payment Collection
The initialize_checkout endpoint accepts a required amount, reference, redirect_url, customer_name, and customer_email to generate a hosted payment session, returning a data object that contains the redirect URL. Once a payment is made, query_charge lets you fetch the current status and full details of that charge using its reference. For bulk reconciliation, get_all_pay_ins supports date-range filtering (from, to), pagination (page, limit), status filtering (e.g., success, failed), and currency filtering, returning an array of pay-in transaction records.
Virtual Accounts and Cards
create_virtual_bank_account provisions a virtual Nigerian bank account tied to a specific customer, with optional fields for kyc_bvn, bank_code, and a permanent flag controlling whether the account is reusable or one-time. The paired query_virtual_bank_account endpoint retrieves account details by account_reference. create_virtual_card issues a new virtual card by specifying a brand, initial amount, currency, and a card_holder_reference, returning a data object with card details.
Payouts and Balances
initiate_payout supports both bank account and mobile money disbursements. For bank transfers, supply bank_code and recipient details; for mobile money, supply operator (e.g., safaricom-ke) and mobile_number. query_payout retrieves payout status by reference. get_balances returns real-time available and pending balance figures for the authenticated account with no required inputs.
Bank Account Verification
verify_bank_account is the verification endpoint: it accepts a 10-digit account_number and a bank_code, and returns account_name, bank_name, bank_code, and account_number when the account resolves successfully. The currency parameter currently accepts only NGN, making this strictly a Nigerian bank resolution endpoint. It returns an upstream error response when the account number is invalid or cannot be resolved.
The Korapay API is a managed, monitored endpoint for developers.korapay.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when developers.korapay.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official developers.korapay.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Validate Nigerian bank account ownership before disbursing funds by calling verify_bank_account with the recipient's account_number and bank_code.
- Provision dedicated virtual bank accounts for marketplace sellers using create_virtual_bank_account with a permanent flag.
- Build a payment checkout flow by calling initialize_checkout and redirecting customers to the returned URL.
- Reconcile monthly pay-in transactions using get_all_pay_ins with date range and status filters.
- Automate payroll disbursements across Nigerian bank accounts and Kenyan mobile money via initiate_payout.
- Monitor wallet liquidity in real time by polling get_balances for available and pending figures.
- Issue virtual cards for employee expense management using create_virtual_card with a cardholder reference.
| 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 | 100 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 actually return?+
account_name (the registered holder name), bank_name, bank_code, and account_number. The endpoint only supports NGN accounts — pass the 10-digit account number and the numeric bank code. If the account cannot be resolved, the endpoint returns an upstream error rather than an empty result.Can I filter pay-in transaction history by specific bank or payment channel?+
get_all_pay_ins endpoint supports filtering by status, currency, date range (from/to), and pagination (page/limit). Filtering by specific bank or payment channel is not currently exposed. You can fork this API on Parse and revise it to add those filters if the underlying data supports them.Does this API cover GHS or KES bank account verification, not just NGN?+
verify_bank_account endpoint only supports Nigerian bank accounts (NGN). The payout endpoints do reference GHS and KES currencies and mobile money operators, but account name resolution is NGN-only. You can fork this API on Parse and revise it to add verification endpoints for other supported currencies if Korapay exposes that capability.Is there a way to retrieve the transaction history for virtual cards?+
create_virtual_card but does not expose a card transaction history endpoint. You can fork this API on Parse and revise it to add a card transactions endpoint.