Skip to main content

API Reference

API docs by Redocly

PayKore Partner API (1.0.0)

Download OpenAPI specification:Download

The PayKore Partner API enables fintech companies to embed wallets, payments, transfers, and KYC into their products.

All requests require a Bearer JWT in the Authorization header. Amounts are always in kobo (1 NGN = 100 kobo).

Wallets

Create a wallet

Creates a wallet in pending state and queues async NUBAN provisioning. The wallet transitions to active when the MFB provisions the account. Listen for the wallet.activated webhook event.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
user_ref
required
string

Unique identifier for the wallet owner in your system.

currency
string
Default: "NGN"

Only NGN is supported.

object

Responses

Request samples

Content type
application/json
{
  • "user_ref": "string",
  • "currency": "NGN",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a wallet

Returns wallet details including current balance and account status.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List wallet transactions

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <uuid>
query Parameters
cursor
string

Opaque pagination cursor from the previous response.

limit
integer [ 1 .. 100 ]
Default: 20

Number of records to return (default 20, max 100).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Transfers

Wallet-to-wallet transfer

Transfers funds between two PayKore wallets instantly, with no NIP fee.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
source_wallet
required
string <uuid>
dest_wallet
required
string <uuid>
amount
required
integer >= 1

Amount in kobo.

reference
required
string

Idempotency key — safe to retry with same value.

description
string

Responses

Request samples

Content type
application/json
{
  • "source_wallet": "8e90aa32-88d9-4da3-aef5-262da327d9cd",
  • "dest_wallet": "4adb59ad-15f7-414e-994a-0bd1ea058671",
  • "amount": 1,
  • "reference": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Outbound bank transfer (NIP)

Initiates an outbound NIP transfer to any Nigerian bank account. The transaction starts as processing and moves to completed or failed via the transfer_status MFB webhook. Listen for transaction.completed and transaction.failed partner webhook events.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
source_wallet
required
string <uuid>
required
object (BankAccount)
amount
required
integer >= 1

Amount in kobo.

reference
required
string

Idempotency key.

description
string

Responses

Request samples

Content type
application/json
{
  • "source_wallet": "8e90aa32-88d9-4da3-aef5-262da327d9cd",
  • "dest_account": {
    },
  • "amount": 1,
  • "reference": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Payments

Create a QR payment request

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
wallet_id
required
string <uuid>
amount
required
integer >= 1
reference
required
string
description
string
expires_in_seconds
integer
Default: 300

Responses

Request samples

Content type
application/json
{
  • "wallet_id": "d9a8fbfc-848f-43a2-9168-911ed3a04a48",
  • "amount": 1,
  • "reference": "string",
  • "description": "string",
  • "expires_in_seconds": 300
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Pay a QR payment request

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
qr_reference
required
string
source_wallet
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "qr_reference": "string",
  • "source_wallet": "8e90aa32-88d9-4da3-aef5-262da327d9cd"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Initiate a USSD payment

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
wallet_id
required
string <uuid>
amount
required
integer >= 1
reference
required
string
phone
required
string

Customer's phone number in E.164 format.

Responses

Request samples

Content type
application/json
{
  • "wallet_id": "d9a8fbfc-848f-43a2-9168-911ed3a04a48",
  • "amount": 1,
  • "reference": "string",
  • "phone": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Split payment across multiple wallets

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
source_wallet
required
string <uuid>
reference
required
string
description
string
required
Array of objects (SplitEntry) >= 2 items

Responses

Request samples

Content type
application/json
{
  • "source_wallet": "8e90aa32-88d9-4da3-aef5-262da327d9cd",
  • "reference": "string",
  • "description": "string",
  • "splits": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

KYC

Submit BVN for verification

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
user_ref
required
string
bvn
required
string^\d{11}$

11-digit Bank Verification Number.

Responses

Request samples

Content type
application/json
{
  • "user_ref": "string",
  • "bvn": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Submit NIN for verification

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
user_ref
required
string
nin
required
string^\d{11}$

11-digit National Identification Number.

Responses

Request samples

Content type
application/json
{
  • "user_ref": "string",
  • "nin": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get KYC verification status for a user

Authorizations:
ApiKeyAuth
path Parameters
userRef
required
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Webhooks

List webhook endpoints

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Register a webhook endpoint

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>
events
required
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a webhook endpoint

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": "INVALID_TOKEN",
  • "message": "invalid or expired token"
}

Compliance

Get compliance status

Returns the partner's KYB compliance record and step completion status.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Submit business information

Submits CAC number and business type. Can be resubmitted to correct mistakes.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
cac_number
required
string

CAC registration number (RC/BN/IT followed by 5–8 digits).

business_type
required
string
Enum: "llc" "sole_prop" "ngo" "partnership"

Responses

Request samples

Content type
application/json
{
  • "cac_number": "RC123456",
  • "business_type": "llc"
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Submit directors / beneficial owners

Submits director information. BVN and NIN are encrypted at rest. BVN verification runs asynchronously — listen for the kyc.verified event.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
required
Array of objects non-empty
Array (non-empty)
full_name
required
string
role
required
string
bvn
string^\d{11}$
nin
string^\d{11}$

Responses

Request samples

Content type
application/json
{
  • "directors": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Accept legal agreements

All three agreements must be accepted simultaneously.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
terms
required
boolean
Value: true

Must be true.

aml_policy
required
boolean
Value: true

Must be true.

dpa
required
boolean
Value: true

Must be true.

Responses

Request samples

Content type
application/json
{
  • "terms": true,
  • "aml_policy": true,
  • "dpa": true
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

Submit use case description

Describes the partner's intended use of the PayKore API. Submitting this step when all others are complete automatically transitions the overall status to submitted for admin review.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
description
required
string >= 20 characters

Responses

Request samples

Content type
application/json
{
  • "description": "stringstringstringst"
}

Response samples

Content type
application/json
{
  • "status": "ok"
}