Transaction Status

Retrieve information about a specific transaction using its reference ID.

info

This endpoint allows you to check the status of a transaction at any point after initialization. It's particularly useful for reconciliation and customer support.

Overview

The transaction info endpoint provides the current status and details of any wallet top up transaction in the Presto system. This allows you to verify transaction completion, investigate issues, and maintain accurate records for reconciliation.

Endpoint Details

Method: GET
URL: /api/institutions/v1/wallet/transaction/{transaction_reference}
Purpose: Retrieve detailed information about a specific transaction

Authentication Required

All API calls, including transaction info requests, require a valid authentication token in the Authorization header.

Request Specification

Path Parameters

Parameter	Type	Required	Description
transaction_reference	string	Yes	The transaction reference for which to retrieve information

Example Request

GET /api/institutions/v1/wallet/transaction/TRX987654321
Authorization: Bearer {token}

Response Specification

Success Response - Transaction Completed

200 OK

{
  "data": {
    "transaction_reference": "TRX987654321",
    "status": "completed",
    "amount": 50,
    "currency": "LYD",
    "timestamp": "2025-04-13T14:30:45Z"
  }
}

Success Response - Transaction Failed

200 OK

{
  "data": {
    "transaction_reference": "TRX987654321",
    "status": "failed",
    "failure_reason": "Transaction was cancelled"
  }
}

Success Response - Transaction Pending

200 OK

{
  "data": {
    "transaction_reference": "TRX987654321",
    "status": "pending"
  }
}

Response Fields

Field	Type	Description
transaction_reference	string	Unique identifier for the transaction
status	string	"pending", "completed", or "failed"
amount	number	The amount involved in the transaction (present for completed transactions)
currency	string	Currency code for the amount (present for completed transactions)
timestamp	string	ISO 8601 formatted date and time when the transaction was processed (completed only)
failure_reason	string	Human-readable explanation for failed transactions (failed only)

Error Responses

401 Unauthorized - Authentication issues

{
  "message": "Invalid client credentials"
}

404 Not Found - Transaction not found

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

422 Unprocessable Content - Input validation issues

{
  "message": "The transaction_reference field is required."
}

500 Internal Server Error - Unexpected server error

{
  "message": "Failed to retrieve transaction information"
}

Error Handling

Common Errors

HTTP Status	Error Type	Example Message	When it Occurs / Resolution
401	Unauthorized	{"message": "Invalid client credentials"}	Missing or invalid authentication token. Provide a valid token.
404	Transaction not found	{"message": "Transaction reference not found"}	The transaction reference does not exist.
422	Validation error	{"message": "The transaction_reference field is required."}	Required fields are missing or invalid.
500	Internal server error	{"message": "Failed to retrieve transaction information"}	Unexpected server error. Try again or contact support.

Use Cases

This endpoint is particularly useful for:

1. Transaction Verification - Confirm if a transaction was successfully processed
2. Reconciliation - Compare transaction records between your system and Presto
3. User Support - Investigate transaction issues when providing customer support
4. Auditing - Maintain comprehensive transaction records for compliance

Implementation Tips

Best Practices

• Store transaction details in your system for easier customer support and reconciliation
• When implementing polling, use increasing intervals between requests (e.g., 2s, 4s, 8s)
• Have a maximum number of retry attempts to avoid infinite polling loops
• If a transaction shows as failed, you can provide appropriate feedback to your customers