Direct debit

A direct debit mandate is a customer’s permission for you to charge their wallet on a schedule, such as a monthly subscription. The customer approves it once, and NeraSika then charges them automatically on each due date.

Direct debit works on MTN, Telecel and AirtelTigo.

Lifecycle

1. Create the mandate. NeraSika replies 202 with status processing.
2. The customer approves it on their phone. The result goes to merchantCreateDDMCallbackURL.
3. NeraSika charges automatically from firstPaymentDate, at the chosen frequency. Each result goes to merchantPayDDMCallbackURL.
4. The mandate ends when you cancel it or when it reaches expiryDate.

Create a mandate

POST/api/v1/transactions/directdebit/mandates

{
  "phone": "0241234567",
  "network": "MTN",
  "amount": "50.00",
  "agreeTnC": "1",
  "desc": "GymMembership",
  "frequency": "04",
  "firstPaymentDate": "2026-11-01",
  "expiryDate": "2027-11-01",
  "merchantRef": "member-883",
  "merchantCreateDDMCallbackURL": "https://example.com/mandate-created",
  "merchantPayDDMCallbackURL": "https://example.com/mandate-payment"
}

Field	Required	Description
phone	Yes	The customer’s mobile money number.
network	Yes	MTN, Telecel or AirtelTigo.
amount	Yes	Amount charged each time, in GHS. Must be within your direct debit limit.
agreeTnC	Yes	Must be "1", confirming the customer agreed to your terms.
desc	Yes	Letters and numbers only, with no spaces or punctuation, such as GymMembership.
frequency	Yes	How often to charge. See the table below.
firstPaymentDate	No	Date of the first charge. Can’t be in the past.
expiryDate	Yes	Date the mandate ends. Can’t be in the past.
merchantRef	Yes	Your own reference for the mandate.
merchantCreateDDMCallbackURL	Yes	Receives the approval result.
merchantPayDDMCallbackURL	Yes	Receives the result of each scheduled charge.

Frequency

Code	Charges
02	Daily
03	Weekly
04	Monthly
05	Every 3 months
06	Every 6 months
07	Yearly

Response

202 Accepted

{
  "success": true,
  "message": "Success",
  "data": {
    "mandateId": "6718a2c4e5f0a1b2c3d4e5f7",
    "merchantRef": "member-883",
    "status": "processing",
    "firstPaymentDate": "2026-11-01T00:00:00.000Z",
    "expires": "2027-11-01T00:00:00.000Z"
  }
}

Store mandateId. When the customer responds, merchantCreateDDMCallbackURL receives active: true if they approved. See Callbacks.

Get a mandate

GET/api/v1/transactions/directdebit/mandates/{mandateId}

Returns the mandate, whether it is active, and its nextPaymentDate. While the mandate is waiting for approval, this also checks with the network for the customer’s response.

{
  "success": true,
  "message": "Success",
  "data": {
    "mandateId": "6718a2c4e5f0a1b2c3d4e5f7",
    "active": true,
    "amount": 50,
    "desc": "GymMembership",
    "payer": "233241234567",
    "agreeTnc": "1",
    "frequency": "04",
    "firstPaymentDate": "2026-11-01T00:00:00.000Z",
    "nextPaymentDate": "2026-12-01T00:00:00.000Z",
    "expiryDate": "2027-11-01T00:00:00.000Z"
  }
}

Change the amount

PUT/api/v1/transactions/directdebit/mandates/{mandateId}

{ "amount": "60.00" }

The new amount applies to future scheduled charges. It must be within your direct debit limit.

Charge now

POST/api/v1/transactions/directdebit/payment

Charges an active mandate immediately, outside its schedule.

{
  "mandateId": "6718a2c4e5f0a1b2c3d4e5f7",
  "amount": "50.00",
  "merchantRef": "member-883-extra",
  "merchantCallbackURL": "https://example.com/mandate-payment"
}

The response (202) contains the new payment transaction. Its _id is the transactionId to use for status checks. The result goes to merchantCallbackURL.

The mandate must be active and not expired, or the request is rejected with 400.

Cancel a mandate

PUT/api/v1/transactions/directdebit/cancel

{
  "mandateId": "6718a2c4e5f0a1b2c3d4e5f7",
  "merchantCancelCallbackURL": "https://example.com/mandate-cancelled"
}

• MTN mandates are cancelled immediately.
• Telecel cancellations are confirmed by the network. The response says processing and the final result goes to merchantCancelCallbackURL.

Caution

Cancel is a PUT request, not POST.

Failed charges

If a scheduled charge fails, for example because the customer’s balance is too low, the result callback has status: "failed". A failed charge can be tried again by the scheduler while the mandate is active. Successful charges move nextPaymentDate forward by one period.

Errors

Status	Message	Cause
400	Description must be alphanumeric	desc has spaces or punctuation.
400	Invalid frequency type	frequency isn’t 02 to 07.
400	Must agree to Ts n Cs. Please specify 1	agreeTnC isn’t "1".
400	Mandate not active	The mandate isn’t approved yet, or was cancelled.
400	Mandate has expired	The mandate passed its expiry date.
403	Transaction type not allowed for merchant	That direct debit action isn’t enabled for your account.
404	Mandate not found	The ID is wrong, or the mandate isn’t yours.