Offline / USSD

Same endpoint and auth as web payments — add one field. Use this when your own USSD menu collects the payer and you need Payloqa to fire the MoMo prompt.

Send mode: "offline" on POST /v1/payments/sessions. Omitting mode keeps today’s web behaviour (widget-safe).

Offline always uses AppsNmobile and the ussd fee channel (including your ussd channel overrides). There is no OTP — the handset MoMo prompt is the second factor.

Your account must be approved for offline collections, and the secret key must include the collections:offline scope. Idempotency-Key is mandatory. msisdn must be 233XXXXXXXXX (12 digits).

Create offline collection

POST/v1/payments/sessions

Auth: Authorization: Bearer sk_test_ or sk_live_

Request body

{
  "mode": "offline",
  "msisdn": "233244123456",
  "amount_minor": 2000,
  "network": "mtn",
  "reference": "order-42"
}

201

{
  "id": "pay_01EXAMPLE",
  "mode": "offline",
  "channel": "ussd",
  "network": "mtn",
  "goods_minor": 2000,
  "amount_minor": 2060,
  "expected_fee_minor": 60,
  "expected_net_minor": 2000,
  "status": "created",
  "reference": "order-42",
  "payer_msisdn": "0244123456"
}

curl 'https://api.payloqa.com/v1/payments/sessions' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_test_...' \
  -H 'Idempotency-Key: ussd-confirm-001' \
  -d '{
  "mode": "offline",
  "msisdn": "233244123456",
  "amount_minor": 2000,
  "network": "mtn",
  "reference": "order-42"
}'

Initiate MoMo prompt

POST/v1/payments/sessions/pay_01EXAMPLE/initiate

Auth: Authorization: Bearer sk_test_ or sk_live_

Returns immediately after the rail accepts the push — do not block your USSD session on customer approval.

Request body

{}

Response

{
  "id": "pay_01EXAMPLE",
  "status": "initiated",
  "mode": "offline",
  "channel": "ussd"
}

curl 'https://api.payloqa.com/v1/payments/sessions/pay_01EXAMPLE/initiate' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_test_...' \
  -d '{}'

Code	HTTP	When
offline_mode_not_enabled	403	Merchant is not approved for offline collections
offline_scope_required	403	API key lacks collections:offline
invalid_msisdn	400	msisdn is not 233XXXXXXXXX