v1.0 Live

Koriepay API Reference

The Koriepay API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the API in test mode, which doesn't affect your live data or interact with the NIBSS or GIM-UEMOA banking networks. The API key you use to authenticate the request determines whether the request is live mode or test mode.

Base URL

https://api.koriepay.com/v1

Authentication

Authenticate your account when using the API by including your secret API key in the request. You can manage your API keys in the Developer Dashboard. Your API keys carry many privileges, so be sure to keep them secure!

Authentication to the API is performed via HTTP Bearer Auth. Provide your API key as the bearer token value in the Authorization header.

Token Type	Description
sk_test_...	Test Secret Key. Use this to mock transactions in the sandbox.
sk_live_...	Live Secret Key. Real transactions moving actual NGN/XOF funds.

Create a Charge

To charge a credit card or mobile money wallet, you create a Charge object. If your API key is in test mode, the supplied payment source won't actually be charged, though everything else will occur as if in live mode.

Parameters

amount Required

Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 500000 to charge ₦5,000.00).
currency Required

Three-letter ISO currency code, in uppercase. Currently supported currencies are NGN (Naira) and XOF (CFA Franc).
source

A payment source to be charged. This can be the ID of a card (tokenized card string) or a saved customer ID (cus_...).

Authentication Example

curl https://api.koriepay.com/v1/charges \
  -H "Authorization: Bearer sk_test_v98djx..."

const koriepay = require('koriepay')(
  'sk_test_v98djxP2lM...'
);

Create a Charge Request

curl -X POST https://api.koriepay.com/v1/charges \
  -H "Authorization: Bearer sk_test_v98djx..." \
  -d amount=2500000 \
  -d currency=NGN \
  -d source=tok_mastercard \
  -d description="Payment for Order #1234"

const charge = await koriepay.charges.create({
  amount: 2500000, // ₦25,000.00
  currency: 'NGN',
  source: 'tok_mastercard',
  description: 'Payment for Order #1234',
});

Response 200 OK

{
  "id": "ch_1Hh1Wp2eZvKYlo2C...",
  "object": "charge",
  "amount": 2500000,
  "amount_captured": 2500000,
  "currency": "NGN",
  "paid": true,
  "status": "succeeded",
  "receipt_url": "https://koriepay.com/r/..."
}