Skip to content

Payment Status

Retrieve the current status and details of a previously created transaction. Two lookup methods are available: by gateway reference (assigned by PayAlo) or by merchant reference (your idempotency key).

Endpoints

Endpoint Route Description
Get by gateway reference GET /gateway/mmo/v2/status/{gatewayReference} Look up a transaction by the gatewayReference returned at creation
Get by merchant reference GET /gateway/mmo/v2/status/mref/{merchantReference} Look up a transaction by the merchantReference you submitted

When to Use

  • Primary: As a fallback when callbacks are missed, delayed, or your callback endpoint was temporarily unavailable.
  • Reconciliation: Run periodic jobs to reconcile your records against the gateway.
  • Polling: If your architecture requires polling rather than webhooks, use this endpoint with reasonable backoff (minimum 2 minutes between polls).

The preferred integration model is to rely on callbacks and use these endpoints only for reconciliation.

Get by Gateway Reference

GET /gateway/mmo/v2/status/{gatewayReference}
Parameter Location Type Required Description
gatewayReference Path string Yes The gatewayReference returned by any payment initiation endpoint (ULID format)

Example Request

GET /gateway/mmo/v2/status/b2p01j3abcdef0000000000000000a1b2 HTTP/1.1
Host: api.payalo.com
X-Api-Key: <your-api-key>

Get by Merchant Reference

GET /gateway/mmo/v2/status/mref/{merchantReference}
Parameter Location Type Required Description
merchantReference Path string Yes The merchantReference you submitted when creating the transaction (max 255 chars)

Example Request

GET /gateway/mmo/v2/status/mref/dep-20240601-001 HTTP/1.1
Host: api.payalo.com
X-Api-Key: <your-api-key>

Response

Success — 200 OK

Both endpoints return the Transaction object.

Field Type Description
status string "pending", "success", or "failed"
type string "payin", "payout", or "tax"
flow string "direct", "web", "qr", or "push"
gatewayReference string Unique transaction ID assigned by the gateway (ULID format)
merchantReference string | null Your idempotency key. null for push transactions (provider-initiated, no merchant request).
reconciliationReference string | null Your reconciliation reference, or merchantReference if not provided. null for push transactions.
providerReference string | null Payment provider's own transaction reference
party Msisdn Party Payer or payee details
method string Payment method key used
country string ISO 3166-1 alpha-2 country code
requestedAmount Money Amount originally requested
finalAmount Money | null Final settled amount (may differ from requested), null if not yet settled
labels object | null Key-value metadata submitted with the transaction. null for push transactions (no merchant request to attach metadata to).
createdAt string Creation timestamp (ISO 8601 UTC)
completedAt string | null Completion timestamp (ISO 8601 UTC), null if still pending
completionSource string | null What resolved the transaction. Known values: "webhook", "poll", "manual". null if still pending.
errorCode string | null Machine-readable error code if the transaction failed
errorMessage string | null Human-readable description of the error
providerData Provider Data | null Provider-specific details, null if not yet routed

Example Response — Successful Transaction

{
  "status": "success",
  "type": "payin",
  "flow": "direct",
  "gatewayReference": "b2p01j3abcdef0000000000000000a1b2",
  "merchantReference": "dep-20240601-001",
  "reconciliationReference": "INV-2024-001",
  "providerReference": "MPESA-REC-99887766",
  "party": {
    "id": "user-42",
    "msisdn": "+254712345678",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]"
  },
  "method": "mpesa-ke",
  "country": "KE",
  "requestedAmount": {
    "value": 500.00,
    "currency": "KES"
  },
  "finalAmount": {
    "value": 500.00,
    "currency": "KES"
  },
  "labels": {
    "orderId": "ORD-2024-001",
    "channel": "mobile-app"
  },
  "createdAt": "2024-06-01T12:34:56.000000Z",
  "completedAt": "2024-06-01T12:36:30.000000Z",
  "completionSource": "webhook",
  "errorCode": null,
  "errorMessage": null,
  "providerData": {
    "name": "mpesa",
    "title": "M-Pesa Kenya",
    "fee": {
      "value": 10.00,
      "currency": "KES"
    },
    "partyData": null,
    "errorCode": null,
    "errorMessage": null
  }
}

Example Response — Failed Transaction

{
  "status": "failed",
  "type": "payin",
  "flow": "direct",
  "gatewayReference": "b2p01j3abcdef0000000000000000a1b2",
  "merchantReference": "dep-20240601-002",
  "reconciliationReference": "INV-2024-002",
  "providerReference": null,
  "party": {
    "id": "user-42",
    "msisdn": "+254712345678",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": null
  },
  "method": "mpesa-ke",
  "country": "KE",
  "requestedAmount": {
    "value": 500.00,
    "currency": "KES"
  },
  "finalAmount": null,
  "labels": null,
  "createdAt": "2024-06-01T12:34:56.000000Z",
  "completedAt": "2024-06-01T12:36:30.000000Z",
  "completionSource": "webhook",
  "errorCode": "user_insufficient_funds",
  "errorMessage": "The user has insufficient funds.",
  "providerData": {
    "name": "mpesa",
    "title": "M-Pesa Kenya",
    "fee": null,
    "partyData": null,
    "errorCode": "2001",
    "errorMessage": "Insufficient balance"
  }
}

Example Response — Pending Transaction

{
  "status": "pending",
  "type": "payout",
  "flow": "direct",
  "gatewayReference": "b2p01j3bcdefg0000000000000000c9d0",
  "merchantReference": "payout-20240601-001",
  "reconciliationReference": "REF-2024-001",
  "providerReference": null,
  "party": {
    "id": "user-42",
    "msisdn": "+254712345678",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": null
  },
  "method": "mpesa-ke",
  "country": "KE",
  "requestedAmount": {
    "value": 1000.00,
    "currency": "KES"
  },
  "finalAmount": null,
  "labels": null,
  "createdAt": "2024-06-01T12:45:00.000000Z",
  "completedAt": null,
  "completionSource": null,
  "errorCode": null,
  "errorMessage": null,
  "providerData": null
}

Error Responses

HTTP Status Error Code Scenario
401 unauthorized API key is missing or invalid
404 not_found Transaction does not exist or does not belong to your brand

See Error Handling for the full error response structure.

Example Error Response — 404 Not Found

{
  "type": "https://docs.payalo.com/errors/not_found",
  "title": "Not found",
  "status": 404,
  "detail": "Transaction not found",
  "errorCode": "not_found"
}

Type and Flow Values

Type Mapping

Value Description
payin Deposit (funds from end user to merchant)
payout Withdrawal (funds from merchant to end user)
tax Tax authority payout

Flow Mapping

Value Description
direct Server-to-server (e.g., STK push, direct disbursement)
web Hosted Payment Page redirect
qr QR code-based payment
push Provider-initiated (offline deposit). No matching create endpoint — these transactions appear in your records when the gateway receives a notification from the provider that an end user paid through their channel. merchantReference, reconciliationReference, and labels are always null for this flow.