Skip to navigation
CollectPaymentsManage Transactions

Search Payments by Merchant Reference

Search for payments using a merchant reference. Returns matching transactions across the specified merchant IDs. See the Payment Status & Recovery guide for using this endpoint to recover payment state after a timeout.

Semantics:

  • Matching on merchantReference is exact and case-sensitive — no partial or prefix matching.
  • Transactions in any state (pending, in-flight, terminal) are returned, and a transaction is searchable immediately after initiation — there is no consistency delay.
  • Only transactions are searched. A checkout session against which no payment was ever initiated does not appear; only collections are returned (never payouts).
  • merchantReference is unique per merchant for new sessions (duplicates are rejected with 409 DUPLICATE_REFERENCE at session creation), but sessions created before uniqueness was enforced may share a reference — so the result is an array.
  • At most 100 matching transactions are returned.
  • The parent session is available on each result under identifiers.sessionId.

Query parameters

merchantIdsstringRequired

Comma-separated list of merchant IDs (UUIDs) to search within.

merchantReferencestringRequired
The merchant reference to search for.

Response

Matching transactions returned successfully. The array is empty when no transaction carries the reference — including when a session was created but no payment was ever initiated against it.

currentStatestring
Current transaction state
previousStateslist of strings
Array of previous transaction states
processorstring
Payment processor used for the transaction
merchantNamestring
Merchant name
transactionIdstring
Unique transaction identifier
amountdouble

Transaction amount as a decimal in major units (e.g. 10 = 10.00 KES) — unlike session creation, which takes minor units.

transactionTypestring
Transaction type
paymentMethodIdstring
Payment method identifier
currencystring
Transaction currency
merchantReferencestring
Merchant reference
transactionStateslist of maps from strings to any
Detailed transaction state history
paymentAttributesmap from strings to stringsOptional

Payment-specific attributes and metadata

identifiersmap from strings to stringsOptional

Additional transaction identifiers. For collections this includes sessionId — the checkout session the transaction belongs to — and payerId, the persistent payer identifier.

paymentInstrumentmap from strings to anyOptional
Payment instrument details when applicable.
processorReferencestringOptional
Payment processor reference
financialTransactionReferencestringOptional
Financial transaction reference from the processor
currentAttemptIdstringOptional
Current attempt identifier
batchPayoutIdstringOptional
Batch payout identifier, if the transaction is part of a batch payout
refundTransactionIdslist of stringsOptional

Transaction identifiers of all refunds processed against this transaction. Each entry can be passed to GET /payment/{transactionId} to retrieve full refund state. UUID v7.

Errors

401
Unauthorized Error
422
Unprocessable Entity Error