Direct debit

get/v1/mandatesList direct debit mandates
post/v1/mandatesAsk a customer for a direct debit mandate
get/v1/mandates/{id}Get a mandate
post/v1/mandates/{id}/refreshCheck a pending mandate now
post/v1/mandates/{id}/chargeDebit an active mandate
post/v1/mandates/{id}/cancelCancel a mandate

List direct debit mandates

get/v1/mandates

Parameters

customerstring (uuid)in query

statuspending | active | canceled | failedin query

bash

curl https://sandbox.api.biftpay.com/v1/mandates \
  -H "Authorization: Bearer bp_test_..."

Responses

200
OKobject
Fields
object"list"required
dataarray of Mandaterequired
Fields of data
idstring (uuid)required
object"mandate"required
livemodebooleanrequired
customerstring (uuid)required
customer_emailstring | nullrequired
customer_namestring | nullrequired
statuspending | active | canceled | failedrequired
pending: waiting for the customer or their bank. active: can be charged.
authorization_urlstring | nullrequired
Where the customer approves it (only while pending).
bank_namestring | nullrequired
account_namestring | nullrequired
account_number_last4string | nullrequired
failure_reasonstring | nullrequired
Why it failed: expired (not approved in 7 days) or the provider's reason.
created_atstring (date-time)required
activated_atstring (date-time) | nullrequired
canceled_atstring (date-time) | nullrequired
has_morebooleanrequired

Ask a customer for a direct debit mandate

post/v1/mandates

Send the customer to authorization_url: they choose their bank and approve debits there. The mandate is active once their bank confirms it (it can take up to a day); until then it's pending, and one not approved in 7 days fails. Then charge it with POST /v1/mandates/{id}/charge. Nigeria only (naira), for the banks the provider supports.

Parameters

Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

Body

customerstring (uuid)

An existing customer. Send this or customer_email.

customer_emailstring (email)

customer_namestring

callback_urlstring (uri)

Where the customer goes after approving it.

bash

curl -X POST https://sandbox.api.biftpay.com/v1/mandates \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

201
Created (pending)Mandate
Fields
idstring (uuid)required
object"mandate"required
livemodebooleanrequired
customerstring (uuid)required
customer_emailstring | nullrequired
customer_namestring | nullrequired
statuspending | active | canceled | failedrequired
pending: waiting for the customer or their bank. active: can be charged.
authorization_urlstring | nullrequired
Where the customer approves it (only while pending).
bank_namestring | nullrequired
account_namestring | nullrequired
account_number_last4string | nullrequired
failure_reasonstring | nullrequired
Why it failed: expired (not approved in 7 days) or the provider's reason.
created_atstring (date-time)required
activated_atstring (date-time) | nullrequired
canceled_atstring (date-time) | nullrequired
400
Invalid request

Get a mandate

get/v1/mandates/{id}

Parameters

idstring (uuid)in pathrequired

bash

curl https://sandbox.api.biftpay.com/v1/mandates/{id} \
  -H "Authorization: Bearer bp_test_..."

Responses

200
OKMandate
Fields
idstring (uuid)required
object"mandate"required
livemodebooleanrequired
customerstring (uuid)required
customer_emailstring | nullrequired
customer_namestring | nullrequired
statuspending | active | canceled | failedrequired
pending: waiting for the customer or their bank. active: can be charged.
authorization_urlstring | nullrequired
Where the customer approves it (only while pending).
bank_namestring | nullrequired
account_namestring | nullrequired
account_number_last4string | nullrequired
failure_reasonstring | nullrequired
Why it failed: expired (not approved in 7 days) or the provider's reason.
created_atstring (date-time)required
activated_atstring (date-time) | nullrequired
canceled_atstring (date-time) | nullrequired
404
Not found, or not visible to this key

Check a pending mandate now

post/v1/mandates/{id}/refresh

Asks the provider whether the customer has approved it (Biftpay also checks every few minutes).

Parameters

idstring (uuid)in pathrequired

bash

curl -X POST https://sandbox.api.biftpay.com/v1/mandates/{id}/refresh \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

Responses

200
OKMandate
Fields
idstring (uuid)required
object"mandate"required
livemodebooleanrequired
customerstring (uuid)required
customer_emailstring | nullrequired
customer_namestring | nullrequired
statuspending | active | canceled | failedrequired
pending: waiting for the customer or their bank. active: can be charged.
authorization_urlstring | nullrequired
Where the customer approves it (only while pending).
bank_namestring | nullrequired
account_namestring | nullrequired
account_number_last4string | nullrequired
failure_reasonstring | nullrequired
Why it failed: expired (not approved in 7 days) or the provider's reason.
created_atstring (date-time)required
activated_atstring (date-time) | nullrequired
canceled_atstring (date-time) | nullrequired
404
Not found, or not visible to this key

Debit an active mandate

post/v1/mandates/{id}/charge

Creates a payment for the amount and debits the customer's account. The business bears the fee. A bank debit can take a while: the payment stays processing until the bank confirms, then payment_intent.successful or payment_intent.failed is sent. The same Idempotency-Key never debits twice.

Parameters

idstring (uuid)in pathrequired

Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

Body

amountintegerrequired

In kobo.

at least 100

currency"NGN"required

descriptionstring

referencestring

metadataobject

bash

curl -X POST https://sandbox.api.biftpay.com/v1/mandates/{id}/charge \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "NGN"
  }'

Responses

201
The paymentPaymentIntent
Fields
idstring (uuid)required
object"payment_intent"required
livemodebooleanrequired
amountintegerrequired
Minor units (kobo, cents).
at least 0
currencyNGN | USDrequired
statuscreated | processing | successful | failed | abandoned | canceledrequired
created not paid yet; processing the customer started paying (entered a card, or was given an account to transfer into); successful the money arrived; failed the last try failed and the customer may try again; abandoned processing for 30 minutes with no money (the customer may still pay); canceled canceled by the business. Money that arrives late always makes a payment successful.
referencestring | null
descriptionstring | null
customer_emailstring | null
brandstring (uuid) | null
customerstring (uuid) | null
payment_linkstring (uuid) | null
metadataobjectrequired
up to 20 keys
fee_bearermerchant | customerrequired
Who pays the fee: the merchant (out of the amount) or the customer (on top of it).
amount_chargedobjectrequired
What the customer pays: the amount, plus fee and VAT when the customer bears the fee (an estimate until paid).
feesobjectrequired
An estimate (at the card price) until the payment succeeds; then final, at the price for the channel and provider that took it. Merchant bears the fee: fee + vat + net = amount. Customer bears it: net = amount, and the customer paid amount + fee + vat.
Fields of fees
feeintegerrequired
Minor units (kobo, cents).
at least 0
vatintegerrequired
Minor units (kobo, cents).
at least 0
netintegerrequired
Minor units (kobo, cents).
at least 0
failure_codestring | null
created_atstring (date-time)required
updated_atstring (date-time)required
paid_atstring (date-time) | null
When the payment became successful.
canceled_atstring (date-time) | null
return_urlstring | null
Where checkout sends the customer after paying.
checkout_urlstring
Only in the response that creates the payment: a short link to Biftpay's hosted checkout for it, to send the customer (WhatsApp, SMS, email). Like client_secret, it opens this one payment only.
client_secretstring
Only in the response that creates the payment. Give it to the customer's checkout page; it can act on this one payment only.
400
Invalid request
404
Not found, or not visible to this key
409
The object is in a state that doesn't allow this

Cancel a mandate

post/v1/mandates/{id}/cancel

No more debits can be made with it. Debits already started still finish.

Parameters

idstring (uuid)in pathrequired

Idempotency-Keystringin headerrequired

A unique key per logical request, for example a UUID. Up to 255 characters.

up to 255 characters

bash

curl -X POST https://sandbox.api.biftpay.com/v1/mandates/{id}/cancel \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: $(uuidgen)"

Responses

200
OKMandate
Fields
idstring (uuid)required
object"mandate"required
livemodebooleanrequired
customerstring (uuid)required
customer_emailstring | nullrequired
customer_namestring | nullrequired
statuspending | active | canceled | failedrequired
pending: waiting for the customer or their bank. active: can be charged.
authorization_urlstring | nullrequired
Where the customer approves it (only while pending).
bank_namestring | nullrequired
account_namestring | nullrequired
account_number_last4string | nullrequired
failure_reasonstring | nullrequired
Why it failed: expired (not approved in 7 days) or the provider's reason.
created_atstring (date-time)required
activated_atstring (date-time) | nullrequired
canceled_atstring (date-time) | nullrequired
404
Not found, or not visible to this key