Fetches the latest payment status for a transaction directly from the bank 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 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 bank is queried for the current payment status and the result is mapped to one of our statuses:

• If the bank 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 reported status matches the current status, or the transition is not allowed, or an unrecognized status is returned, 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 an inbound webhook) while the check was in progress, the stale 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 reported by the bank (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 an inbound confirmation or manual reconciliation). The bank 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.