Direct debit mandates
Ask a customer to let you debit their GTBank account, up to a total and between two dates, and debit it when payment is due.
Who can give a mandate
Mandates work with GTBank accounts only. For a customer who banks elsewhere, use a saved card or emailed invoices.
1. Ask for a mandate
POST /v1/mandates with the customer’s name and email, a description of what the debits are for (shown to the customer and their bank), maxAmount (the most you may debit in total, at least ₦200), and a startDate and endDate (YYYY-MM-DD). The start date cannot be in the past, and the end date must be after it. Pass customerId to link it to a customer record.
The mandate starts as awaiting_customer and carries an approvalUrl. rafiqPay emails that link to the customer, unless you pass sendEmail: false and send it yourself.
2. The customer approves it
On the approval page the customer enters their 10-digit GTBank account number, their BVN, their name, phone number and address. Their bank then sends them a code (the mandate is now awaiting_code), and they enter it on the same page. They can ask for a new code if it does not arrive.
Once the code is accepted the mandate is active and you get mandate.active. The approvalUrl is null from then on. If the bank does not accept the request, the status is rejected; if the end date passes first, it is expired.
3. Debit it
POST /v1/mandates/:id/debits with an amount, and optionally a narration and your orderReference. Send an Idempotency-Key so a retry never debits twice.
The answer has a status (succeeded, failed or pending), a failureReason when it failed, and the charge. Each debit is a charge like any other, with the usual fee, and sends charge.succeeded when it settles. A pending debit is checked again by rafiqPay.
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| Active and ready | status, readyToDebit | Optional | The mandate must be active. After approval the bank can take a while to make it ready; until readyToDebit is true, a debit is refused and you should try again later. |
| At least ₦200 | amount | Optional | Each debit must be ₦200 or more. |
| Within the dates | startDate, endDate | Optional | No debit before the start date or after the end date. |
| Within what is left | amountLeft | Optional | Debits together can never be more than maxAmount. amountDebited and amountLeft show where you are. A failed debit does not count. |
Cancelling
POST /v1/mandates/:id/cancel ends the mandate. The bank is told first, so a mandate shown as cancelled can never be debited again. You get mandate.cancelled, and a subscription that was using the mandate goes back to emailing invoices.
Testing
In test mode the code on the approval page is 123456. A debit for an amount ending in 99 kobo is declined.