The Transactions API provides read access to payment transaction records and allows you to force a status refresh. All endpoints use the /api/v1/transactions base path.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/transactions | List transactions with filtering and pagination support |
GET | /api/v1/transactions/{transaction_id} | Retrieve full details of a specific transaction |
POST | /api/v1/transactions/{transaction_id}/refresh-status | Force a status refresh by querying UrbanpayX for the latest payment state |
Transaction Statuses
| Status | Description |
|---|---|
pending | Transaction created, awaiting user to complete checkout |
processing | User authorized the payment, bank transfer in progress |
success | Payment completed successfully |
failed | Payment failed during processing |
canceled | Payment was canceled by the user |
expired | Checkout link expired before the user completed the payment |
Status Refresh
In most cases, transaction statuses are updated automatically via webhooks. Use POST /refresh-status when:
- A webhook delivery was missed or delayed.
- You need to verify the current status in real time before taking action.
- A transaction has been in
processingstatus longer than expected.
Each status transition triggers a payment.status_changed webhook event to your configured endpoint.
Required roles
- List / view transactions: All roles (OWNER, OPERATIONS, DEVELOPER)
- Refresh transaction status: OWNER or OPERATIONS only
See Roles and Permissions for the full matrix.
Related guides
- Transaction Lifecycle — Full state machine, webhook payloads, and handling patterns
- Core Concepts — How transactions fit in the domain model
- Pagination — Transaction list pagination (default: 10, max: 100)
- Error Reference — Transaction-related errors