MTN Direct Debit

Create and manage recurring debit mandates on MTN Mobile Money wallets. A mandate must be approved by the customer before scheduled debits can run.

Direct debit is asynchronous. Create and update requests return a processing response. Use the mandate creation and debit callbacks to confirm final status.

Endpoints

Action	Endpoint	Use For
Create Mandate	`/api/v1.0/new_mtn_recurring_create_mandate/`	Start a new recurring debit approval request.
Update Mandate	`/api/v1.0/new_mtn_recurring_update_mandate/`	Change amount, dates, or frequency for an existing mandate.
Cancel Mandate	`/api/v1.0/new_mtn_recurring_cancel_mandate/`	Cancel an existing approved mandate.
Cancel Pre-approval	`/api/v1.0/new_mtn_recurring_cancel_pre_approval/`	Cancel a customer's pending pre-approval before the mandate becomes active.

Create Mandate

POST https://testxchange.korba365.com/api/v1.0/new_mtn_recurring_create_mandate/

Parameter	Required	Description
client_id	Mandatory	Your Client ID from the Korba Xchange dashboard.
customer_number	Mandatory	Customer MTN wallet number in the format `233xxxxxxxxx`.
transaction_id	Mandatory	Unique reference from your system for the mandate creation request.
amount	Mandatory	Amount to debit on each scheduled cycle.
frequency_type	Mandatory	Schedule type. Supported values are `Daily`, `Weekly`, `Monthly`, and `Yearly`.
frequency	Mandatory	Interval for the selected frequency type, for example `1` for every month.
start_date, end_date	Mandatory	Mandate start and end dates.
debit_day	Mandatory	Day on which scheduled debits should be attempted.
mandate_creation_call_back_url	Mandatory	Callback URL for the customer's approval or rejection of the mandate.
debit_customer_call_back_url	Mandatory	Callback URL for each scheduled debit result.
description, payer_name	Optional	Metadata stored against the mandate transaction.

Create Request

curl -X POST https://testxchange.korba365.com/api/v1.0/new_mtn_recurring_create_mandate/ \
  -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 2,
    "customer_number": "233241234567",
    "transaction_id": "DD-20260626-001",
    "amount": "20.00",
    "frequency_type": "Monthly",
    "frequency": "1",
    "start_date": "2026-07-01",
    "end_date": "2027-06-30",
    "debit_day": "30",
    "mandate_creation_call_back_url": "https://yourapp.com/callbacks/mandate-created/",
    "debit_customer_call_back_url": "https://yourapp.com/callbacks/mandate-debit/",
    "description": "Monthly subscription"
  }'

Update Mandate

POST https://testxchange.korba365.com/api/v1.0/new_mtn_recurring_update_mandate/

Update an existing mandate by passing its mandate_id and the full replacement schedule values.

Parameter	Required	Description
client_id	Mandatory	Your Client ID from the dashboard.
mandate_id	Mandatory	Identifier of the mandate to update.
transaction_id	Mandatory	Unique reference for this update request.
amount	Mandatory	New debit amount for each scheduled cycle.
frequency_type, frequency, start_date, end_date, debit_day	Mandatory	Replacement schedule values for the mandate.
description, payer_name, extra_info	Optional	Metadata stored against the update request.

Update Request

{
  "client_id": 2,
  "mandate_id": "009",
  "transaction_id": "DD-20260626-002",
  "amount": "25.00",
  "frequency_type": "Monthly",
  "frequency": "1",
  "start_date": "2026-08-01",
  "end_date": "2027-07-31",
  "debit_day": "30"
}

Cancel Mandate

POST https://testxchange.korba365.com/api/v1.0/new_mtn_recurring_cancel_mandate/

Cancel Mandate Request

{
  "client_id": 2,
  "mandate_id": "009"
}

Cancel Pre-approval

POST https://testxchange.korba365.com/api/v1.0/new_mtn_recurring_cancel_pre_approval/

Cancel Pre-approval Request

{
  "client_id": 2,
  "customer_number": "233241234567"
}

Responses

200 OK

{
  "success": true,
  "results": "Transaction is being processed.",
  "error_code": null
}

400 Bad Request

{
  "success": false,
  "error_code": 405,
  "error_message": "Duplicate Transaction ID"
}

Callbacks

Korba Xchange calls your callback URLs with the original transaction_id, a status of SUCCESS or FAILED, and a message describing the outcome.

Callback Example

https://yourapp.com/callbacks/mandate-created/?transaction_id=DD-20260626-001&status=SUCCESS&message=Mandate%20approved

Previous Utilities Next USSD OTP