POST /v1/mandates Bearer Idempotent

Set up recurring

Step 1 of the direct debit flow: POST /v1/mandates, then GET /v1/mandates until succeeded, then POST /v1/mandates/{mandate_id}/debits. Returns processing (HTTP 201). The customer may receive a MoMo approval prompt; poll GET or wait for mandate.succeeded before debiting. If the MSISDN already has an approved mandate, create may return succeeded (reuse) so you can debit immediately. A second create while approval is still pending returns HTTP 409 — poll the first merchant_reference. Without plan_id this does not auto-debit. Ghana direct debit is MTN only. Requires Idempotency-Key.

Headers

Idempotency-Key required string: Required for money-moving and session/mandate creates; replays must use the same body.

Body parameters

mobile required string
provider required string
currency required string
amount required string
frequency required string: One of DAILY WEEKLY MONTHLY
starts_at required string (date-time)
merchant_reference required string
description optional string
plan_id optional string: When set, links the mandate to a subscription plan and creates a subscriber.
customer_name optional string: Required when plan_id is set.
customer_email optional string (email): Required when plan_id is set.
notes optional string

Webhook events

mandate.processing mandate.succeeded

POST https://omni.mojo-pay.com/v1/mandates

{
    "currency": "GHS",
    "amount": "1.00",
    "frequency": "DAILY",
    "starts_at": "2026-01-11T00:00:00Z",
    "merchant_reference": "mandateTest010912026003",
    "description": "daily subscription payment",
    "mobile": "233597225334",
    "provider": "MTN"
}

{
    "currency": "GHS",
    "amount": "10.00",
    "frequency": "WEEKLY",
    "starts_at": "2026-01-11T00:00:00Z",
    "merchant_reference": "mandate-weekly-001",
    "description": "Weekly subscription",
    "mobile": "233597225334",
    "provider": "MTN"
}

{
    "currency": "GHS",
    "amount": "50.00",
    "frequency": "MONTHLY",
    "starts_at": "2026-02-01T00:00:00Z",
    "merchant_reference": "mandate-monthly-001",
    "description": "Monthly plan",
    "mobile": "233597225335",
    "provider": "VODAFONE"
}

curl -X POST "https://omni.mojo-pay.com/v1/mandates" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "GHS",
    "amount": "1.00",
    "frequency": "DAILY",
    "starts_at": "2026-01-11T00:00:00Z",
    "merchant_reference": "mandateTest010912026003",
    "description": "daily subscription payment",
    "mobile": "233597225334",
    "provider": "MTN"
}'

Response

{
    "object": "mandate",
    "status": "processing",
    "merchant_reference": "mandateTest010912026003",
    "message_id": "5d3cc227-329f-41e8-a6b4-8eb637bed8b5"
}