API

Payments

Collect mobile money from your customers. Create a session, optionally verify the payer with OTP, initiate the charge, then poll status or listen for webhooks.

Typical web flow: create a payment session → (optional) OTP request + verify → initiate → poll GET …/status until terminal or receive a webhook.

All amounts are integer pesewas. Send Idempotency-Key on create.

Optional — request collection OTP

POST/v1/otp/request

Auth: Authorization: Bearer sk_test_ or sk_live_

Payloqa sends the SMS. Use otp_request_id when creating the payment session.

Request body

{
  "msisdn": "233244123456",
  "purpose": "collection",
  "collection": {
    "amount_minor": 1000
  }
}

201

{
  "otp_request_id": "otpr_01EXAMPLE",
  "expires_at": "2026-08-30T12:10:00.000Z"
}

curl 'https://api.payloqa.com/v1/otp/request' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_test_...' \
  -H 'Idempotency-Key: otp-req-001' \
  -d '{
  "msisdn": "233244123456",
  "purpose": "collection",
  "collection": {
    "amount_minor": 1000
  }
}'

Optional — verify OTP

POST/v1/otp/verify

Auth: Authorization: Bearer sk_test_ or sk_live_

Request body

{
  "otp_request_id": "otpr_01EXAMPLE",
  "code": "123456"
}

Response

{
  "verified": true
}

curl 'https://api.payloqa.com/v1/otp/verify' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_test_...' \
  -d '{
  "otp_request_id": "otpr_01EXAMPLE",
  "code": "123456"
}'

Create payment session

POST/v1/payments/sessions

Auth: Authorization: Bearer sk_test_ or sk_live_

Request body

{
  "msisdn": "233244123456",
  "amount_minor": 1000,
  "network": "mtn",
  "otp_request_id": "otpr_01EXAMPLE"
}

201

{
  "id": "pay_01EXAMPLE",
  "platform_id": "plt_01EXAMPLE",
  "merchant_id": "mch_01EXAMPLE",
  "channel": "web",
  "network": "mtn",
  "goods_minor": 1000,
  "amount_minor": 1000,
  "expected_fee_minor": 25,
  "expected_net_minor": 975,
  "status": "created",
  "client_trans_id": "your-order-123",
  "otp_request_id": "otpr_01EXAMPLE",
  "payer_msisdn": "233244123456",
  "created_at": "2026-08-30T12:00:00.000Z"
}

curl 'https://api.payloqa.com/v1/payments/sessions' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_test_...' \
  -H 'Idempotency-Key: pay-create-001' \
  -d '{
  "msisdn": "233244123456",
  "amount_minor": 1000,
  "network": "mtn",
  "otp_request_id": "otpr_01EXAMPLE"
}'

Initiate charge

POST/v1/payments/sessions/pay_01EXAMPLE/initiate

Auth: Authorization: Bearer sk_test_ or sk_live_

Request body

{}

Response

{
  "id": "pay_01EXAMPLE",
  "status": "initiated",
  "initiated_at": "2026-08-30T12:00:05.000Z"
}

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

Poll status

GET/v1/payments/sessions/pay_01EXAMPLE/status

Auth: Authorization: Bearer sk_test_ or sk_live_

Response

{
  "id": "pay_01EXAMPLE",
  "status": "paid",
  "terminal": true,
  "paid_at": "2026-08-30T12:00:30.000Z",
  "retry_after_seconds": null
}

curl 'https://api.payloqa.com/v1/payments/sessions/pay_01EXAMPLE/status' \
  -H 'Authorization: Bearer sk_test_...'