API Reference · Wallets & accounts

Mandates

Direct-debit mandates on a customer’s GTBank account. The customer approves on a rafiqPay page with a code from their bank; you then debit it, up to a total and between two dates.

The mandate object

Represents a mandate entity in the rafiqPay system.

Field	Type & Flags	Description
id	string	Mandate ID (mnd_...).
mode	enum	live \| test.
status	enum	awaiting_customer (the customer has not given their details) \| awaiting_code (waiting for the code from their bank) \| active \| cancelled \| rejected (the bank did not accept it) \| expired.
readyToDebit	boolean	True once the bank has made an active mandate ready. Debits are refused until then.
customerId	stringNullable	The customer record, when you gave one.
customerName	string	The customer’s name.
customerEmail	string	The customer’s email. The approval link is sent here.
description	string	What the debits are for, shown to the customer and their bank.
maxAmount	string	The most you may debit in total, in naira.
amountDebited	string	What has been debited so far, in naira.
amountLeft	string	What may still be debited, in naira.
startDate	string	First day a debit is allowed (YYYY-MM-DD).
endDate	string	Last day a debit is allowed (YYYY-MM-DD).
bankName	stringNullable	The customer’s bank, once they have given their details.
accountLast4	stringNullable	Last four digits of the customer’s account. The full number is never returned.
approvalUrl	stringNullable	The page where the customer approves. Set only while the status is awaiting_customer or awaiting_code.
lastDebitedAt	stringNullable	When the mandate was last debited.
createdAt	string	When the mandate was asked for (ISO 8601).

Example mandate JSON

mandate example payload

{
  "id": "mnd_01J9KANZU",
  "object": "mandate",
  "mode": "live",
  "status": "active",
  "readyToDebit": true,
  "customerId": "cus_amina_01",
  "customerName": "Amina Bello",
  "customerEmail": "amina@kanzu.ng",
  "description": "Kanzu Academy monthly fees",
  "currency": "NGN",
  "maxAmount": "300000.00",
  "amountDebited": "50000.00",
  "amountLeft": "250000.00",
  "startDate": "2026-11-10",
  "endDate": "2027-11-09",
  "bankName": "GTBank",
  "accountLast4": "6789",
  "approvalUrl": null,
  "lastDebitedAt": "2026-11-10T08:00:12.000Z",
  "createdAt": "2026-11-07T09:30:00.000Z"
}

Endpoints & Operations

POST/v1/mandatesIn plan 035

Ask for a mandate

Creates a mandate request and returns it with approvalUrl. The customer approves on that page, with a code from their bank. GTBank accounts only.

Request Parameters

Parameter	Type	Requirement	Description
customerName	string	Required	The customer’s name (2 to 120 characters).
customerEmail	string	Required	Where the approval link is sent.
description	string	Required	What the debits are for (3 to 100 characters), shown to the customer and their bank.
maxAmount	string	Required	The most you may debit in total, at least "200.00".
startDate	string	Required	YYYY-MM-DD. Not in the past.
endDate	string	Required	YYYY-MM-DD. After the start date.
customerId	string	Optional	Link it to a customer record (cus_...).
sendEmail	boolean	Optional	Email the approval link to the customer. Defaults to true. Pass false to send it yourself.

Request Example

POST /v1/mandates

cURL · v1

curl -X POST "https://api.rafiqpay.net/v1/mandates" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_create-mandate_01" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "cus_amina_01",
  "customerName": "Amina Bello",
  "customerEmail": "amina@kanzu.ng",
  "description": "Kanzu Academy monthly fees",
  "maxAmount": "300000.00",
  "startDate": "2026-11-10",
  "endDate": "2027-11-09",
  "sendEmail": true
}'

Response (200 OK)

Response payload

{
  "id": "mnd_01J9KANZU",
  "object": "mandate",
  "status": "awaiting_customer",
  "readyToDebit": false,
  "maxAmount": "300000.00",
  "amountLeft": "300000.00",
  "approvalUrl": "https://checkout.rafiqpay.net/m/Xq7vR2kLp9TzW4nB8cYdF3mH"
}

GET/v1/mandatesIn plan 035

List mandates

Lists mandates. Filter with customerId and mode.

Request Parameters

Parameter	Type	Requirement	Description
customerId	string	Optional	Only this customer’s mandates.
mode	enum	Optional	live \| test. Defaults to live.

Request Example

GET /v1/mandates

cURL · v1

curl -X GET "https://api.rafiqpay.net/v1/mandates" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a"

Response (200 OK)

Response payload

{
  "object": "list",
  "data": [
    {
      "id": "mnd_01J9KANZU",
      "status": "active",
      "amountLeft": "250000.00"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

GET/v1/mandates/:idIn plan 035

Retrieve a mandate

Retrieves one mandate.

Request Example

GET /v1/mandates/:id

cURL · v1

curl -X GET "https://api.rafiqpay.net/v1/mandates/:id" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a"

Response (200 OK)

Response payload

{
  "id": "mnd_01J9KANZU",
  "object": "mandate",
  "status": "active",
  "readyToDebit": true,
  "amountLeft": "250000.00"
}

POST/v1/mandates/:id/debitsIn plan 035

Debit a mandate

Debits an active, ready mandate. Each debit must be at least ₦200, on or between the start and end dates, and no more than amountLeft. The usual fee applies. A failed debit gives its amount back to amountLeft.

Request Parameters

Parameter	Type	Requirement	Description
amount	string	Required	Decimal Naira amount, at least "200.00".
narration	string	Optional	Shown on the customer’s statement (up to 100 characters).
orderReference	string	Optional	Your own order number (up to 120 characters).

Request Example

POST /v1/mandates/:id/debits

cURL · v1

curl -X POST "https://api.rafiqpay.net/v1/mandates/:id/debits" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_debit-mandate_01" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "50000.00",
  "narration": "Kanzu fees November",
  "orderReference": "KANZU-1110"
}'

Response (200 OK)

Response payload

{
  "status": "succeeded",
  "failureReason": null,
  "charge": {
    "id": "pay_01J9KANZU940",
    "object": "charge",
    "status": "succeeded",
    "method": "direct_debit",
    "currency": "NGN",
    "amount": "50000.00",
    "fee": "750.00",
    "net": "49250.00"
  }
}

POST/v1/mandates/:id/cancelIn plan 035

Cancel a mandate

Ends the mandate. The bank is told first, so it can never be debited again. A subscription using it goes back to emailed invoices.

Request Example

POST /v1/mandates/:id/cancel

cURL · v1

curl -X POST "https://api.rafiqpay.net/v1/mandates/:id/cancel" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_cancel-mandate_01"

Response (200 OK)

Response payload

{
  "id": "mnd_01J9KANZU",
  "object": "mandate",
  "status": "cancelled",
  "readyToDebit": false
}

These events are dispatched to your webhook endpoints when actions occur on this resource:

mandate.active mandate.cancelled charge.succeeded

Mandates

The mandate object

Endpoints & Operations

Ask for a mandate

List mandates

Retrieve a mandate

Debit a mandate

Cancel a mandate

Related Webhook Events