Transaction Status

Retrieve the current state of any Cash In or Cash Out transaction by its reference.

info

This is the authoritative endpoint for resolving an unknown outcome. Whenever a confirm call times out or returns 5xx, query this endpoint before any cash moves.

Overview

The endpoint returns the same shape for both transaction types, distinguished by the type field. It is used for:

1. Resolving timeouts — determining whether a confirm actually landed
2. Reconciliation — matching your end-of-day totals against Presto's
3. Driver support — investigating a disputed settlement or payout
4. Auditing — retaining a verifiable record on both sides

Endpoint details

Method: GET URL: /api/institutions/v1/drivers/transaction/{transaction_reference} Alternate URL: /api/institutions/v1/drivers/transaction?institution_reference={institution_reference} Purpose: Retrieve the status and details of a driver settlement transaction

A transaction can be addressed by either reference. Both forms return exactly the same body — use whichever identifier you hold.

Authentication required

All API calls require a valid bearer token. See Authentication.

Request specification

Path parameters

Parameter	Type	Required	Description
transaction_reference	string	Conditional	Presto's reference, returned by a Cash In or Cash Out init call. Required unless institution_reference is supplied as a query parameter

Query parameters

Parameter	Type	Required	Description
institution_reference	string	Conditional	Your reference, as supplied on init. Use this form when you do not have Presto's transaction_reference

Example request — by Presto reference

GET /api/institutions/v1/drivers/transaction/DS-9F3K2LQ7XB
Authorization: Bearer {token}

Example request — by your own reference

GET /api/institutions/v1/drivers/transaction?institution_reference=IZI-2026-0914-000187
Authorization: Bearer {token}

Recovering from a lost response

If an init call times out, you may never learn the transaction_reference — but you always know the institution_reference you sent. Query by your own reference to find out whether the transaction exists and what state it is in, before deciding whether to re-initialize.

Response specification

Completed Cash In

200 OK

{
  "data": {
    "transaction_reference": "DS-9F3K2LQ7XB",
    "type": "debt_settlement",
    "status": "completed",
    "amount": 200.000,
    "currency": "LYD",
    "timestamp": "2026-09-14T14:30:45Z",
    "institution_reference": "IZI-2026-0914-000187",
    "branch_reference": "TUN-CENTRE-VILLE-04",
    "driver": {
      "uid": "10432",
      "name": "MOH... OK...",
      "phone": "218920000000"
    },
    "balance_after": 140.500
  }
}

Completed Cash Out

200 OK

{
  "data": {
    "transaction_reference": "EP-4T7M1XC9QD",
    "type": "earnings_payout",
    "status": "completed",
    "amount": 100.000,
    "currency": "LYD",
    "timestamp": "2026-09-14T14:35:12Z",
    "institution_reference": "IZI-2026-0914-000188",
    "branch_reference": "TUN-CENTRE-VILLE-04",
    "driver": {
      "uid": "10432",
      "name": "MOH... OK...",
      "phone": "218920000000"
    },
    "balance_after": 28.750
  }
}

Pending

200 OK

{
  "data": {
    "transaction_reference": "EP-4T7M1XC9QD",
    "institution_reference": "IZI-2026-0914-000188",
    "branch_reference": "TUN-CENTRE-VILLE-04",
    "type": "earnings_payout",
    "status": "pending",
    "amount": 100.000,
    "currency": "LYD",
    "ttl": "2026-09-14T18:49:51+00:00"
  }
}

Expired

200 OK

{
  "data": {
    "transaction_reference": "EP-4T7M1XC9QD",
    "institution_reference": "IZI-2026-0914-000188",
    "branch_reference": "TUN-CENTRE-VILLE-04",
    "type": "earnings_payout",
    "status": "expired",
    "amount": 100.000,
    "currency": "LYD"
  }
}

Failed

200 OK

{
  "data": {
    "transaction_reference": "EP-4T7M1XC9QD",
    "institution_reference": "IZI-2026-0914-000188",
    "branch_reference": "TUN-CENTRE-VILLE-04",
    "type": "earnings_payout",
    "status": "failed",
    "amount": 100.000,
    "currency": "LYD",
    "failure_reason": "Too many invalid OTP attempts"
  }
}

Response fields

Field	Type	Description
transaction_reference	string	Unique reference for the transaction
type	string	"debt_settlement" (Cash In) or "earnings_payout" (Cash Out)
status	string	"pending", "completed", "expired" or "failed"
amount	number	Amount involved
currency	string	Currency code
timestamp	string	ISO 8601 date and time the transaction was finalized. Present for completed only
ttl	string	ISO 8601 expiry of the reservation. Present for pending only
institution_reference	string	Your own reference, supplied on init and echoed on every status. Always present
branch_reference	string | null	Your branch or teller reference as supplied on init, or null. Always present
driver	object	Driver the transaction belongs to. Present for completed only
balance_after	number	For debt_settlement, the remaining debt. For earnings_payout, the remaining earnings. Present for completed only
failure_reason	string	Human-readable explanation. Present for failed only

Interpreting each status

Status	Meaning	What the teller should do
pending	Initialized and not yet confirmed, or confirmed but not yet recorded because Presto's side failed. In the second case Presto keeps retrying automatically, and the status later becomes completed	Complete the confirm step, or let it expire. If your confirm returned 5xx, do not resolve the transaction at the counter. Keep polling until it is completed
completed	Money has moved on Presto's side	Cash In: keep the cash. Cash Out: hand over the cash
expired	The 15-minute window passed without confirmation	Cash In: return the cash. Cash Out: do not pay. Re-initialize if the driver still wants to proceed
failed	Confirmation was attempted and rejected	Cash In: return the cash. Cash Out: do not pay. Read failure_reason

Error responses

401 Unauthorized

{
  "message": "Unauthenticated."
}

404 Not Found

{
  "message": "Transaction reference not found"
}

500 Internal Server Error

{
  "message": "Server Error"
}

Error handling

Common errors

HTTP Status	Error Type	Example Message	When it Occurs / Resolution
401	Unauthorized	{"message": "Unauthenticated."}	Missing or invalid token.
404	Not found	{"message": "Transaction reference not found"}	Neither reference matches a transaction, or it belongs to another institution. For an institution_reference you are sure you sent, this means the init never reached Presto — it is safe to re-initialize.
500	Internal server error	{"message": "Server Error"}	Retry with backoff. Do not treat a 500 here as "not completed".

A 500 is not an answer

If the status endpoint itself fails, the transaction's outcome is still unknown. Keep retrying with backoff, and escalate to Presto support rather than deciding the outcome at the counter.

Implementation tips

Best practices

• Poll with increasing intervals (2s, 4s, 8s) and a bounded number of attempts.
• Retain the full response against your own record, matched on institution_reference — it is the shared evidence in any dispute.
• Run a daily sweep over every transaction you initialized to catch references left pending by an interrupted session.