Creating an Authorization

The Direct Debit endpoint allows you to set up a standing authorization on a customer's account, giving you permission to debit that account during the authorization's active period.

Endpoint (POST)

https://api.korapay.com/merchant/api/v1/direct-debit/initiate

The same endpoint is used for variable and fixed authorizations, the debit_type field selects the behaviour.

Variable Authorization

A variable authorization suits businesses needing flexibility to collect different amounts over time. You set the maximum debit amount per transaction for the authorization period, allowing you to debit the customer in varying amounts as necessary, provided no single debit exceeds the defined maximum.

Request Parameters

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`debit_type`	string	Yes	Must be `"variable"`.
`amount`	number	Yes	This field is a positive number with a maximum of 2 decimal places, representing the maximum amount that can be debited in a single transaction under this authorization.
`currency`	string	Yes	Currently only `NGN` is supported.
`description`	string	Yes	Short description shown to the customer (e.g. "Subscription cap").
`start_date`	string (YYYY-MM-DD)	Yes	Date the authorization becomes valid.
`end_date`	string (YYYY-MM-DD)	Yes	Date the authorization expires.
`customer`	object	Yes	Customer details (see below).
`customer.name`	string	Yes	Customer's full name.
`customer.email`	string	Yes	Valid email address.
`customer.account_number`	string	Yes	10‑digit NUBAN.
`customer.bank_code`	string	Yes	NIBSS bank code (3–6 chars).
`customer.phone_number`	string	Yes	11‑digit Nigerian phone, leading 0 (e.g. 08012345678).
`customer.billing_address`	string	No	Customer's billing address.

Sample Request

{
   "amount": 100,
   "currency": "NGN",
   "debit_type": "variable",
   "description": "Monthly subscription for premium plan",
   "start_date": "2026-04-19",
   "end_date": "2026-05-19",
   "customer": {
       "name": "Jane Doe",
       "email": "[email protected]",
       "account_number": "0112345678",
       "bank_code": "058",
       "billing_address": "123 Victoria Island, Lagos",
       "phone_number": "08012345678"
   }
}

Sample Success Response

{
    "status": true,
    "message": "Direct debit authorization initiated successfully",
    "data": {
        "status": "pending",
        "reference": "KPY-DD-AUTH-*********",
        "authorization_code": "KPY-AUTH-******",
        "amount": 100,
        "currency": "NGN",
        "debit_type": "variable",
        "description": "To complete your e-mandate activation, please make a token payment of ₦50.00 to the account number provided below.",
        "customer_account_number": "0112345678",
        "customer_bank_code": "058",
        "customer_account_name": "Jane Doe",
        "customer_bank_name": "GTBank Plc",
        "start_date": "2026-04-19",
        "end_date": "2026-05-19"
    }
}

Fixed Authorization

A fixed authorization is best for businesses that need to charge the same amount on a regular schedule over a defined period. Kora's system automatically processes each scheduled debit for you, for example, a ₦10,000 charge every month for one year.

Additional / changed parameters

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`debit_type`	string	Yes	Must be `"fixed"`
`amount`	number	Yes	The amount to debit on each scheduled run. Positive, max 2 decimal places.
`frequency`	string	Yes	One of `weekly, biweekly, monthly, bimonthly, quarterly, semi_annually, yearly,` or the custom values `days, weeks, months`.
`interval`	integer (1–365)	Conditional	Required when `frequency` is `days, weeks, or months` (e.g. frequency: "days", interval: 14 for every 14 days). Forbidden for the named frequencies.
`retrial_frequency`	integer (1–3)	Yes	Number of retry attempts per scheduled debit if it fails.
`initial_debit_date`	string (YYYY-MM-DD)	Yes	Date of the first scheduled debit. Must fall within `start_date–end_date`.
`description`	string	Yes	Short description.
`start_date, end_date, customer.*, currency`	—	Same as variable debit	See Variable Authorization

Sample Request

{
    "debit_type": "fixed",
    "amount": 10000,
    "currency": "NGN",
    "description": "Monthly gym subscription",
    "start_date": "2026-05-01",
    "end_date": "2027-05-01",
    "frequency": "monthly",
    "retrial_frequency": 3,
    "initial_debit_date": "2026-05-05",
    "customer": {
      "name": "John Doe",
      "email": "[email protected]",
      "phone_number": "08087654321",
      "account_number": "0011223344",
      "bank_code": "058"
    }
  }

Sample Success Response

{
  "status": true,
  "message": "success",
  "data": {
    "status": "pending",
    "authorization_code": "KPY-AUTH-2c4a9b1f",
    "amount": 10000,
    "currency": "NGN",
    "debit_type": "fixed",
    "customer_account_number": "0011223344",
    "customer_bank_code": "058",
    "customer_account_name": "JOHN ADEYEMI DOE",
    "start_date": "2026-05-01",
    "end_date": "2027-05-01",
    "description": "Monthly gym subscription"
  }
}