The ledger

Every collection, payout and refund is a transaction. How they're typed, how they resolve, and how references keep retries safe.

RazPay keeps one ledger per project. Each row is a transaction: money in, or money out.

`type`	`direction`	What it is
`collection`	`in`	A customer paid you: a payment request, a charge under a pre-approval, or a paid invoice.
`payout`	`out`	You sent money from your disbursement account to someone.
`refund`	`out`	You returned money for an earlier collection.

Lifecycle

Every transaction starts pending and ends successful or failed. It never changes after that.

You create it (collect, pay out or refund). RazPay records it as pending and sends the instruction to the provider.
The provider resolves it. MTN tells RazPay through a callback, and RazPay also checks every pending transaction in the background, so a missed callback never leaves one stuck.
RazPay records the result and sends your project a webhook.

If the provider rejects the request outright (an unknown number, for example), the API call itself fails and the transaction is recorded as failed.

A transaction the provider still can’t resolve after 24 hours is closed as failed with the reason expired: provider returned no terminal status within the reconciliation window. In practice a customer has about 5 minutes to approve a MoMo prompt.

References and retries

You give every transaction an external_reference: your own order id, payout id or similar. It’s unique within your project, across every type: a payout can’t reuse a collection’s reference.

The reference makes every write safe to retry. Sending the same request again with the same external_reference returns the original transaction instead of charging or paying twice. If your request times out, retry it with the same reference.

Look any transaction up by its reference with GET /payments/{reference}.

The transaction object

external_referencestringrequired

Your reference for this transaction.

typestringrequired

collection, payout or refund.

directionstringrequired

in for collections, out for payouts and refunds.

provider_idstringrequired

The provider it went through, e.g. momo.

provider_refstring

The reference RazPay gave the provider (MoMo’s X-Reference-Id). Quote it when you contact the provider.

amountnumberrequired

Amount in major units, e.g. 30.00.

currencystringrequired

ISO 4217 code, e.g. SZL.

statusstringrequired

pending, successful or failed.

financial_tx_idstring

The provider’s financial transaction id, once successful.

failure_reasonstring

Why it failed, in plain words. Only when status is failed. See Errors.

payer_phonestring

The number that paid. Collections only.

payee_phonestring

The number that received the money. Payouts and refunds only.

party_namestring

The wallet owner’s name, when RazPay looked it up (payouts, and refunds of those payments).

descriptionstring

The description you sent.

refund_ofstring

For a refund, the external_reference of the collection it returns.

metadataobjectrequired

Your own data, stored and returned exactly as sent. RazPay never reads it.

created_atintegerrequired

Unix time (seconds) it was created.

updated_atintegerrequired

Unix time (seconds) of its last change.