Transaction lookup

The transaction-lookup endpoints are for administrative read access — reconciliation, customer-support investigations, batch exports. They return a richer payload than the runtime getTransactionState API and accept date-range queries.

For runtime / wallet-side transaction queries, see Querying transactions instead.

Endpoints

A PSP sees transactions across all its merchants. A merchant sees only its own transactions. Acquirers don't have access to these endpoints — they have separate reporting in the Portal UI.

Look up a single transaction

Returns the full TransactionExportBean for one transaction.

Request:

curl -X POST https://qa.scantopay.io/portal/restful/transactions/81234 \
  -u 'PSP_42:yourPspApiPassword'

(The {txRef} is the transaction ID — a long, typically 5-7 digits in sandbox and larger in production.)

Response: a TransactionExportBean with the canonical export shape:

{
  "dateCreated": "2026-05-14 11:42:25",
  "transactionId": 81234,
  "msisdn": "27832006283",
  "txType": "PAYMENT",
  "currencyCode": "ZAR",
  "amount": 5.75,
  "txState": "SUCCESS",
  "bankStatus": "00",
  "authCode": "A1B2C3",
  "retrievalReferenceNumber": "282352",
  "merchantId": 25,
  "merchantName": "Acme Coffee Pty Ltd",
  "subMerchantName": null,
  "reference": "PAYAT0000039172",
  "card": "****1234",
  "appType": "AMT",
  "serial": null,
  "acquirerCode": "00",
  "acquirerDescription": "Approved",
  "cardSerial": "N/A",
  "binLast4": "1234"
}

Field reference (verified against TransactionExportBean.java):

Look up transactions by date

Returns every transaction in your scope between two dates.

Request:

curl -X POST https://qa.scantopay.io/portal/restful/transactionsByDate \
  -u 'PSP_42:yourPspApiPassword' \
  -H 'Content-Type: application/json' \
  -d '{
    "dateFrom": "2026-05-01 00:00:00",
    "dateTo":   "2026-05-14 23:59:59"
  }'

Request fields:

Response: an array of TransactionExportBean — same shape as single lookup, one per transaction. Empty array if no transactions fall in the range.

Common errors:

Look up transactions by MSISDN

Returns every transaction in your scope for a given cardholder MSISDN, within a date range.

Request:

curl -X POST https://qa.scantopay.io/portal/restful/transactionsByMsisdn \
  -u 'PSP_42:yourPspApiPassword' \
  -H 'Content-Type: application/json' \
  -d '{
    "msisdn":   "27832006283",
    "dateFrom": "2026-05-01 00:00:00",
    "dateTo":   "2026-05-14 23:59:59"
  }'

Request fields:

Response: an array of TransactionExportBean.

📘

If the MSISDN doesn't match any cardholder on the platform, the response is 200 OK with an empty array — not a 404. This avoids leaking whether an arbitrary MSISDN has ever transacted.

Common errors:

How this differs from the Remote API's transactionState

Use this page for offline reconciliation and reporting jobs. Use Querying transactions for runtime checks.

Picking a date range

A few practical notes:

• The platform timezone is SAST (UTC+2) for all date fields — supply your dateFrom / dateTo in SAST, not UTC.
• There's no hard cap on the range you can query, but pulling more than a month at a time is slow and the response can be large. For monthly reports, prefer one call per day or per week.
• The boundaries are inclusive — a transaction at exactly dateFrom is included.

What's next

• Pull the certificate PDF for a transaction → Transaction certificates
• Look up state for a wallet UI (runtime) → Querying transactions
• Decode any state value → Transaction states
• Decode bank decline codes → ISO response codes
• Cross-cutting rules → Business rules