Create Direct Debit Mandate

Get started with creating a direct debit mandate via API reference

Check Mandate Status

Check mandate status via API reference.
Direct Debit is a payment method that allows businesses to collect funds directly from their customers’ bank accounts with their authorization. This method is particularly useful for recurring payments, such as subscriptions or utility bills, as it provides a convenient and automated way to manage payments. Direct Debit transactions are typically initiated by the business, but they require prior consent from the customer, ensuring that the process is secure and transparent.

​
Create Direct Debit Mandate

To begin with the process of creating a Direct Debit mandate. The customer authorize the business, allowing them to debit their bank account for specified amounts and frequencies. The mandate includes details such as the customer’s bank account information, the amount to be debited, start date, end date and the frequency of the debits. In order to authorize the mandate, the customer will transfer an amount (N50) to the NIBSS provided account for validation.
It’s important to note that the amount should be sent from the customer’s account number that is being used for the mandate
To create a direct debit mandate, send a POST request to this endpoint /v1/direct-debits. 
curl --request POST \
--url https://api.nomba.com/v1/direct-debits \
--header 'Authorization: Bearer <token>' \
--header 'accountId: <accountId>' \
--header 'Content-Type: application/json' \
--data'{
  "customerAccountNumber": "2334334532",
  "bankCode": "101",
  "customerName": "Kolapo Adeoti",
  "customerAddress": "maryland Ikeja computer village",
  "customerAccountName": "Kolapo Adeoti",
  "frequency": "VARIABLE",
  "narration": "test e mandate response",
  "customerPhoneNumber": "08022222222",
  "merchantReference": "12003074001223212",
  "startDate": "2025-08-29T15:30",
  "endDate": "2025-08-30T10:40",
  "customerEmail": "[email protected]",
  "startImmediately": true
}'
The frequency field determines how often the customer’s account will be debited once the mandate is active. Businesses can choose from multiple options depending on their billing model.
FrequencyDescription
VARIABLEThe debit amount is not fixed. The business specifies the amount each time.
WEEKLYDebit occurs once every week.
MONTHLYDebit occurs once every month.
QUARTERLYDebit occurs once every three months.
EVERY_TWO_MONTHSDebit occurs once every two months.
EVERY_THREE_MONTHSDebit occurs once every three months.
EVERY_FOUR_MONTHSDebit occurs once every four months.
EVERY_FIVE_MONTHSDebit occurs once every five months.
EVERY_SIX_MONTHSDebit occurs once every six months.
EVERY_SEVEN_MONTHSDebit occurs once every seven months.
EVERY_EIGHT_MONTHSDebit occurs once every eight months.
EVERY_NINE_MONTHSDebit occurs once every nine months.
EVERY_TEN_MONTHSDebit occurs once every ten months.
EVERY_ELEVEN_MONTHSDebit occurs once every eleven months.
EVERY_TWELVE_MONTHSDebit occurs once every twelve months (yearly).
Once the mandate is created, it undergoes a verification process to ensure that the provided bank account details are valid and the customer’s bank authorizes the request. This step can take up to 72 hours for some banks to authorize the mandate.

​
Check Mandate Status

The status of the mandate is crucial for managing Direct Debit transactions. The possible statuses include ACTIVE, SUSPENDED, and DELETED. To check a mandate status, send a GET request to this endpoint /v1/direct-debits/status?mandateId={mandateId}. 
curl --request GET \
  --url https://api.nomba.com/v1/direct-debits/status?mandateId={mandateId} \
  --header 'Authorization: Bearer <token>' \
  --header 'accountId: <accountid>'
  --header 'Content-Type: application/json' \
The mandate advice status indicates whether the mandate has been approved by the customer’s bank for debit. The possible statuses are ADVICE_NOT_SENT and ADVICE_SENT. It’s essential to check the mandate advice status before initiating any debit transactions to ensure that the mandate is valid and active.

​
Debit Mandate

After the mandate is verified and activated, the business can initiate Direct Debit transactions according to the agreed schedule. The specified amounts will be automatically debited from the customer’s bank account and credited to the business’s account.
Please not the following :
  • Only mandates with an ACTIVE status can be used for debit transactions.
  • Only mandates with an ADVICE_SENT status can be used for debit transactions.
To debit a mandate created, send a GET request to this endpoint /v1/direct-debits/debit-mandate. 
curl --request POST \
  --url https://api.nomba.com/v1/direct-debits/debit-mandate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountid>' \
  --data '{
  "mandateId": "89b0efc0-dde5-49e2-8bde-23ae081c43",
  "amount": "110.00"
}'

​
GET MANDATE

To get a single mandate created, send a GET request to this endpoint /v1/direct-debits/<mandateId>, you will pass the mandateID as path parameter. 
curl --request GET \
  --url http://api.nomba.com/v1/direct-debits/<mandateId> \
  --header 'Authorization: Bearer <token>' \
  --header 'accountId: <accountId>' \
  --header 'Content-Type: application/json' \

​
List Direct debit

To list all direct debit created, send a GET request to this endpoint /v1/direct-debits/mandates. 
    curl --request GET \
    --url https://api.nomba.com/v1/direct-debits/mandates?page=0&pageSize=20 \
    --header 'Authorization: Bearer <token>' \
    --header 'accountId: <accountid>'
    --header 'Content-Type: application/json' \

​
Update Direct debit Status

The status of the mandate can be updated as needed. For instance, if a customer wishes to cancel the mandate, the business can update the mandate status accordingly. To update a direct debit status, send a PUT request to this endpoint /v1/direct-debits/update-status. 
curl --request PUT \
  --url https://api.nomba.com/v1/direct-debits/update-status \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountid>' \
  --data '{
  "mandateId": "c93e1e1b-85f5-461e-8b9b-74ee091d4aa4",
  "status": "SUSPEND"
}'