Get a transaction by merchant reference

GET

/Transactions/GetTransactionByMerchantReference

const url = 'https://cybqa.pesapal.com/pesapalv3/api/Transactions/GetTransactionByMerchantReference?merchantReference=example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://cybqa.pesapal.com/pesapalv3/api/Transactions/GetTransactionByMerchantReference?merchantReference=example' \
  --header 'Authorization: Bearer <token>'

Returns the same data as getTransactionStatus, keyed by the id you supplied when creating the order. Useful when the order_tracking_id has been lost.

Merchant references are not guaranteed unique across an account, so prefer getTransactionStatus in normal operation.

Authorizations

bearerAuth

Parameters

Query Parameters

merchantReference

required

string

The id sent when the order was created.

Responses

200

Returned for both success and failure.

application/json

One of:

object
object

object

status_code

required

1 is a completed payment, 2 is a failed one. 0 and 3 are sometimes cited but have never been observed.

integer

Allowed values: 1 2

payment_status_description

string

confirmation_code

No fixed format. A card payment returns 22 numeric digits, a completed M-Pesa payment returns the alphanumeric receipt code the customer also gets by SMS, and a failed one returns a short numeric value.

It cannot be stored as a number: UI76G5D93D is not numeric, and the card form exceeds what a 64-bit float represents exactly. Type it as a string with no assumed length or character set.

string

payment_method

Differs between lookup endpoints for the same payment.

string

payment_account

The masked card number or the phone number used.

string

amount

number

currency

string

merchant_reference

string

order_tracking_id

string format: uuid

description

A human-readable outcome on a card payment, for example Transaction successfully processed. Null on a mobile money payment whether it completed or failed, so it cannot be relied on to be present.

string | null

created_date

East Africa Time with no timezone designator, unlike created_date on an IPN registration, which is UTC. Parsing this as UTC shifts every payment by three hours.

string

message

string

call_back_url

string | null

account_number

string | null

payment_status_code

Empty on a completed payment. On a failed one it sometimes names the reason, for example request_terminated_by_user when the customer declined a mobile money prompt, and is sometimes still empty. Read status_code for the outcome and treat this as optional detail.

string

error

On a successful lookup this is an object whose fields are all null, not null itself, so a truthiness check misreports success as failure.

object

error_type

null

code

null

message

null

status

string | null

An application error, returned with HTTP 200.

object

error

required

A populated error. Every field is present and non-null.

object

error_type

required

string

Allowed values: api_error invalid_request_error authentication_error

code

required

Mostly snake_case, but not consistently: InvalidIpnId is PascalCase. Compare exactly.

string

message

required

Multiple validation errors arrive pipe-delimited in one string, and malformed JSON produces leading empty segments.

string

status

Usually "500". Never matches the HTTP status.

string | null

Example

{
  "status_code": 1,
  "payment_status_description": "Completed",
  "confirmation_code": "7884396530786173704004",
  "created_date": "2026-09-03T15:47:34.567"
}