Exirom Payment API Documentation

This guide explains how to interpret transaction statuses in the Exirom payment lifecycle. It is designed for developers and technical customers integrating with Exirom.

Every transaction in Exirom goes through various statuses from creation to completion. Some statuses are intermediate (in-progress) while others are outcomes. Below is a list of common transaction statuses and their meanings in the payment lifecycle:

#Transaction Status

Status	Description	Lifecycle Stage
NEW	The transaction has been created but not yet processed. This is the initial state right after you submit a payment request, before any further action is taken (initial stage of the lifecycle).	Intermediate
PENDING	The transaction is in progress or awaiting an external action (for example, waiting for customer authentication or bank confirmation) before it can be completed. In this intermediate state, the outcome is not yet final - the transaction will eventually transition to a success or failure once the external process completes. See Error Recovery Patterns for handling long-pending transactions.	Intermediate
PROCESSING	The transaction is currently being processed by the system.	Intermediate
CUSTOMER_VERIFICATION	Customer interaction required (e.g., 3D Secure authentication).	Intermediate
SUCCEED	The transaction completed successfully - funds have been captured or transferred, and the payment is finalized (no further action needed). This is a final status indicating the payment was processed as expected.	Final
FAILED	The transaction did not complete due to an error or a payment decline. No funds were transferred, and the process has ended (a final status). This indicates the payment was unsuccessful, often due to issues like insufficient funds, network errors, or validation problems. See Error Recovery Patterns for retry strategies.	Final
CANCELLED	The transaction was canceled by the user or the system before it was completed. This means the process was terminated prematurely (no funds were captured). Canceled is a final status, and the payment will not proceed further.	Final
REFUNDED	The transaction was successfully reversed after being completed. In other words, a previously successful payment has been refunded to the customer, returning the funds to their account (final status). This typically occurs after a SUCCEED status, if a refund operation is performed.	Final
CHARGEBACK	The transaction was disputed and later reversed by the payment network or bank via a chargeback. This status indicates that although the transaction might have initially succeeded, the funds have been forcibly returned due to a dispute (final status). Chargebacks usually result from customer disputes or fraud claims.	Final

#State Transitions

Not all transitions are possible. See Transaction Lifecycle Flow for the full diagram.

#Key Rules

Intermediate → Final only. Once a transaction reaches SUCCEED, FAILED, CANCELLED, CHARGEBACK, or REFUNDED, it cannot change status (except SUCCEED → REFUNDED or SUCCEED → CHARGEBACK).
REFUNDED is a new transaction. When you call POST /api/v1/refunds/card, a separate refund transaction is created. The original payment's status changes to REFUNDED.
CHARGEBACK is externally triggered. Chargebacks are initiated by the card network or issuing bank, not by API call.
When status is FAILED, check the declineCode field for the reason. See Decline Codes Reference.

👍 “Final” status means no further state changes will occur for that transaction, whereas intermediate statuses like NEW/PENDING will eventually transition to a final outcome.