Collect payments

Ask a customer to approve a payment on their phone, and know reliably when it's done.

A collection sends a payment prompt to the customer’s MoMo wallet. They approve it with their PIN, and the money lands in your collection account.

The flow

Send the request

Call POST /payments/collect with your reference, the amount and the customer’s number. You get back a pending transaction straight away.

Tell the customer to approve

Show a “check your phone” message. They have about 5 minutes to approve before MoMo expires the request.

Fulfil on the webhook

When the payment resolves you receive transaction.successful or transaction.failed. Deliver the order on successful; on failed, show the failure_reason and let them try again with a new reference.

curl -X POST https://api.razpay.razonetix.com/v1/payments/collect \
  -H "Authorization: Bearer $RAZPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference": "order-1001",
    "provider": "momo",
    "amount": 30.00,
    "currency": "SZL",
    "phone_number": "76123456",
    "description": "Basic plan, 50 minutes",
    "metadata": { "order_id": "1001", "plan": "basic" }
  }'

Don’t rely on one signal

Treat the webhook as the main signal and polling as the backup:

If your page is waiting on the customer, poll GET /payments/{reference} every few seconds for a couple of minutes. Each poll of a pending payment also asks MTN for its status.
Run a periodic job that checks any order you still think is pending. RazPay reconciles everything in the background too, and closes anything unresolved after 24 hours as failed.

Phone numbers

MoMo numbers in Eswatini are 8 digits starting with 76 or 78. RazPay accepts 76123456, +26876123456, 268 76 123 456 and similar, and stores the canonical 26876123456. An invalid number is rejected before anything is created, so you can safely retry with the same reference once it’s fixed.

Rejecting inactive wallets up front

Switch on Check wallets before collecting in the project’s payment settings and RazPay asks MTN whether the number is an active wallet before sending the prompt. An inactive number is rejected with phone_number is not registered for mobile money, or the account is not active. If the check itself can’t run, the payment goes ahead normally.

Descriptions

description appears in both parties’ MoMo transaction history. MoMo limits it to 160 characters and rejects some symbols, so RazPay trims it and drops anything other than letters, digits, spaces and basic punctuation (. , - _ : / # ( ) + @).

Metadata

Put whatever your system needs in metadata: order ids, plan names, user ids. RazPay stores it and returns it unchanged on the transaction and in every webhook, and never reads it.