Transaction Lifecycle

Every payment in UrbanPayX is represented by a Transaction. Understanding how transactions move through statuses is essential to building a reliable payment integration.

Transaction statuses

A transaction always has one of six statuses:

Terminal means the transaction will not change status again. Once a transaction reaches success, failed, expired, or canceled, it is final.

State transitions

Not every transition is possible. Here is the complete state machine:

                    +------------------------------------------+
                    |                                          |
                    v                                          |
              +----------+                                     |
              | PENDING  |---------------------+               |
              +----------+                     |               |
                    |                          |               |
                    | User starts checkout     | Time passes   | User/system cancels
                    v                          v               |
              +----------+              +----------+           |
              |PROCESSING|              | EXPIRED  | <---------+ (from PROCESSING too)
              +----------+              +----------+
                    |
          +---------+---------+
          |         |         |
          v         v         v
     +---------+ +------+ +----------+
     | SUCCESS | |FAILED| | CANCELED |
     +---------+ +------+ +----------+

Allowed transitions:

Blocked transitions: Any terminal status to any other status. A success transaction stays success forever.

What triggers status changes

Transaction statuses are updated by two mechanisms:

1. Inbound provider webhooks. When the upstream payment provider notifies UrbanPayX of a status change, the transaction is updated automatically. This is the primary mechanism and requires no action from you.

2. Manual refresh. You can call the refresh endpoint to check the current status with the provider:

POST /api/v1/transactions/{transaction_id}/refresh-status
Authorization: Bearer YOUR_ACCESS_TOKEN

This is useful if you suspect a webhook was missed or want to verify the current state. It is rate-limited — you will get a 429 with a retry-after value if you call it too frequently.

Refresh restrictions: Only pending and processing transactions can be refreshed. Refreshing a terminal transaction returns 400.

How you will know: webhooks

When a transaction status changes, UrbanPayX sends a payment.status_changed webhook to your configured webhook_url. The payload looks like this:

{
  "id": "event-uuid",
  "type": "payment.status_changed",
  "version": "v1",
  "occurred_at": "2026-03-26T10:15:00Z",
  "client_id": "your-client-uuid",
  "data": {
    "transaction_id": "tx-uuid",
    "ref_id": "abc123def456",
    "transfer_id": "payment-network-transfer-id",
    "user_id": "user-uuid",
    "business_customer_id": null,
    "project_id": "project-uuid",
    "previous_payment_status": "pending",
    "current_payment_status": "processing",
    "actor_type": null,
    "actor_account_id": null
  }
}

Key fields in data:

The raw upstream provider status is deliberately not included in the client webhook. Use GET /api/v1/transactions/{transaction_id}/status-events if you need the fine-grained payment status for a transition.

Webhook security: Every webhook includes an X-UPX-Signature header containing an HMAC-SHA256 signature and an X-UPX-Timestamp header. Verify the signature against the payload using your webhook secret to ensure the event came from UrbanPayX.

Recommended handling patterns

For each status

pending — The payment link has been created. Show the user a "Waiting for payment" state. If you are displaying the checkout URL in your UI, this is the starting point.

processing — The user is actively completing payment. Show a "Payment in progress" indicator. Do not let the user initiate a new payment for the same intent — they are already in the flow.

success — Payment is confirmed. Mark the order as paid, deliver the product/service, send a confirmation to the user. This is the happy path.

failed — The bank rejected the payment. Show an error to the user and offer to retry with a new transaction. Do not retry with the same transaction — create a new one.

expired — The payment link was not used in time. Inform the user and offer a new payment link if the intent is still valid. Create a new transaction.

canceled — The user or system canceled the payment. Handle similarly to expired — offer a new payment link if needed.

Idempotent transaction creation

Always include an X-Idempotency-Key header when creating transactions. This prevents duplicate payments if your request is retried (network timeout, user double-clicks, etc.).

The key should be unique per payment intent. If you retry the same key with the same payload, you will get the original transaction back. If you retry with a different payload, you will get a 409 Conflict.

# First request
X-Idempotency-Key: order-12345-attempt-1

# Safe retry (same payload) — returns the same transaction
X-Idempotency-Key: order-12345-attempt-1

# New payment intent — use a new key
X-Idempotency-Key: order-12345-attempt-2

Webhooks vs. polling

Use webhooks as your primary mechanism. They are real-time, reliable, and do not consume your rate limit.

Use polling as a fallback — for example, if you suspect a webhook was lost, or during initial testing when webhooks are not set up yet. Remember:

• Only pending and processing transactions can be refreshed.
• There is a cooldown between refresh calls per transaction.
• The refresh endpoint returns the updated transaction object.

Handling the callback URL

After the user completes (or abandons) the checkout flow, they are redirected to your callback_url. This is a user-facing redirect, not a server-to-server call. Do not rely on the callback to determine payment success — the user might close their browser before the redirect completes.

Always use webhooks (or polling as fallback) to confirm the final transaction status server-side.

Detail status vs payment status

Alongside the six coarse statuses above, UrbanPayX exposes a finer-grained detail status for
diagnosing where in the bank flow a payment sits. It appears as provider_status on
POST /api/v1/transactions/{transaction_id}/refresh-status and on each entry of
GET /api/v1/transactions/{transaction_id}/status-events. It is deliberately not part of the
webhook payload.

These are UrbanPayX values, not the upstream network's raw codes: unrecognized upstream codes
collapse to the coarse status (or unknown), so a code the network adds later can never leak
through this boundary.

The last row matters: those detail statuses are recorded on the transaction timeline but do not
move the coarse status, so they never produce a payment.status_changed webhook on their own.

Related guides

• Getting Started — Create your first transaction end to end
• Error Reference — What each error code means and how to fix it
• Webhook Setup — Configure webhooks, verify signatures, handle retries