Transactions And Statements

Pagamio holds a record of every purchase made through your widget. You can read it server-to-server, per customer, and download a daily statement of wallet activity to reconcile your ledger.

All endpoints on this page use Authorization: ApiKey <YOUR_API_KEY> and return errors in the standard envelope. Amounts are in rand (amount is a decimal, currency is ZAR).

List Transactions

Path: GET {WIDGET_BASE_URL}/partner/v1/transactions

Required scope: transactions:read

Query parameter	Required	Description
customerId	One of customerId / walletId	Your customer identifier, as given at session creation (or the launch token's sub).
walletId	One of customerId / walletId	Your wallet identifier.
status	No	PENDING, COMPLETED, FAILED or ESCALATED.
from, to	No	ISO 8601 instants, filtered on createdAt. Both are inclusive.
page	No	Zero-based page number. Default 0.
size	No	Page size. Default 20, maximum 100.

A request with neither customerId nor walletId returns 422 VALIDATION: you cannot list every customer's transactions in one call.

curl "$WIDGET_BASE_URL/partner/v1/transactions?customerId=customer-123&status=COMPLETED&size=20" \
  -H "Authorization: ApiKey $PAGAMIO_API_KEY"

{
  "content": [
    {
      "id": "c2a9d3f0-5b7e-4c1a-8e21-0d6f4a9b7c33",
      "status": "COMPLETED",
      "productCode": "VOD-ANY",
      "productName": "Vodacom Airtime",
      "amount": 25.00,
      "currency": "ZAR",
      "paymentMethod": "PARTNER_WALLET",
      "createdAt": "2026-09-30T10:04:02Z",
      "completedAt": "2026-09-30T10:04:11Z"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "pageNo": 0
}

Get One Transaction

Path: GET {WIDGET_BASE_URL}/partner/v1/transactions/{id}

Required scope: transactions:read

Returns the fields above plus receipt once the purchase has completed and a receipt was recorded (for example an electricity token or a voucher PIN). Treat the receipt as sensitive. An unknown id, or one that belongs to another partner, returns 404 TRANSACTION_NOT_FOUND.

Status Values

status	Meaning
PENDING	In progress, including a purchase whose outcome is still being confirmed.
COMPLETED	Product delivered and the wallet captured (or being captured).
FAILED	Not delivered; funds released.
ESCALATED	Could not be settled automatically; Pagamio operations are resolving it. Ask your Pagamio contact for its status.

FAILED and ESCALATED rows carry failureCode (machine-readable) and failureReason (a sentence). Neither is present on other statuses.

failureCode	Meaning
INSUFFICIENT_FUNDS	Your wallet declined the hold for lack of funds.
CUSTOMER_NOT_FOUND	Your wallet does not know the customer.
WALLET_BLOCKED	Your wallet is inactive or blocked.
LIMIT_EXCEEDED	Over a limit on your wallet.
VALIDATION	The purchase details were not accepted.
PRODUCT_UNAVAILABLE	The product is temporarily unavailable.
AGGREGATOR_DECLINED	The product provider declined the purchase.
TIMEOUT	The outcome could not be confirmed in time.
UNKNOWN	Any other reason.

Daily Statement (Payment Legs)

Path: GET {WIDGET_BASE_URL}/partner/v1/reconciliation/payment-legs?date=YYYY-MM-DD

Required scope: reconciliation:read

Returns every wallet payment leg created on one business day, for reconciling against your own ledger. The business day is Africa/Johannesburg midnight to midnight, on the time the leg was created. date must be a valid date that is not in the future. A day with more than 10,000 rows returns 422 VALIDATION.

{
  "date": "2026-09-29",
  "partnerCode": "acme",
  "generatedAt": "2026-09-30T03:15:02Z",
  "rows": [
    {
      "paymentLegId": "b1f5a2c0-8a1e-4f0b-9d4e-2c6a1f7e9a10",
      "transactionId": "c2a9d3f0-5b7e-4c1a-8e21-0d6f4a9b7c33",
      "customerId": "customer-123",
      "walletId": "wallet-456",
      "amount": 25.00,
      "currency": "ZAR",
      "productCode": "VOD-ANY",
      "legState": "DEDUCTED",
      "holdRef": "hold-789",
      "captureRef": "cap-101",
      "voidRef": null,
      "coreTransactionId": "core-tx-1",
      "createdAt": "2026-09-29T10:00:00Z",
      "updatedAt": "2026-09-29T10:00:05Z",
      "outcome": "DEDUCTED"
    }
  ]
}

• paymentLegId is the reference your wallet received on every hold, capture and release call.
• holdRef, captureRef and voidRef are the identifiers your wallet returned (holdId, captureId/hold id, releaseId/hold id).
• customerId and walletId are your own identifiers.

outcome

outcome	Meaning	Your ledger should show
DEDUCTED	Hold captured.	Final deduction.
RELEASED	Hold released.	Funds available again.
DECLINED	Your wallet declined the hold.	No movement.
DEDUCT_OUTSTANDING	Product delivered; capture still being retried.	Held funds. Expect DEDUCTED shortly.
RELEASE_OUTSTANDING	Product not delivered; release still being retried.	Held funds. Expect RELEASED shortly.
ESCALATED	Awaiting manual resolution by Pagamio operations.	Held funds. Pagamio will contact you.
IN_PROGRESS	Still moving through the lifecycle.	Held funds, or no movement yet.

CSV

Send Accept: text/csv for the same rows as RFC 4180 CSV (UTF-8, header row, \r\n line endings) with Content-Disposition: attachment; filename="<partnerCode>-payment-legs-<date>.csv". Text fields that begin with =, +, -, @, a tab or a carriage return are prefixed with a single quote so spreadsheet software never runs them as formulas. Strip that quote when importing programmatically.

Request a day's statement once that business day has ended, so it includes every leg.

---

Last updated: September 2026