Fetches the latest payment status for a transaction directly from the payment provider and updates the stored transaction record if the status has advanced. Only transactions still in a non-terminal state (pending or processing) can be refreshed. Returns the updated transaction along with what changed.

Authentication & access

• Requires a client API token: Authorization: Bearer <token>.
• The caller must hold the transactions.refresh_status permission and have the OWNER or OPERATIONS role.

Path parameter

• transaction_id (string, required) — the UrbanpayX transaction ID to refresh. It must belong to your client.

State preconditions

• The transaction must be in pending or processing status. A transaction already in a terminal state (success, failed, expired, canceled) cannot be refreshed and returns 400.
• A short per-transaction cooldown is enforced between refreshes. Calling again before the cooldown elapses returns 429 with the number of seconds to wait.
• If the transaction has not yet produced an upstream payment session and is not in a reconciliation flow, it has nothing to query upstream and the request returns 400.

Behavior

When the transaction has an upstream payment session, the provider is queried for the current payment status and the result is mapped to an UrbanpayX status:

• If the provider reports a newer status and the transition is allowed, the transaction is updated, updated is true, and a status-change event is emitted. Reaching a terminal status also clears any reconciliation flag.
• If the provider status matches the current status, or the transition is not allowed, or the provider returns an unrecognized status, the transaction is left unchanged (updated is false) and message explains why.
• If the transaction advanced to a terminal state or its session changed concurrently (e.g. via a provider webhook) while the provider was being queried, the stale provider response is not applied; the latest stored state is returned with updated set to false.

Response

200 OK with a TransactionRefreshStatusResponse:

• transaction — the updated TransactionDetailResponse.
• provider_status — the raw status string returned by the payment provider (may be null).
• previous_status — the transaction status before this refresh.
• updated — whether this refresh changed the transaction status.
• message — a human-readable description of the outcome.

A 202 Accepted is returned instead when the transaction has no upstream payment session yet but is in a reconciliation flow (awaiting a provider callback or manual reconciliation). The provider is not queried; the response records the refresh attempt with updated set to false.

Error responses

Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.