A transaction progresses through states that reflect where it is in the authorization and settlement process.
| State (Status) | Description | How it is reached |
|---|---|---|
authorized | Funds are held on the person's account but not yet transferred to the merchant. | A successful sale, auth, or ACH transaction returns this state. |
declined | The issuing bank or processor rejected the transaction. | The processor returns a non-approval response code. |
captured | The authorized amount is marked for settlement. | POST /v1/transactions/{id}/capture on an authorized transaction. For card_sale, capture happens automatically. |
canceled | The transaction is voided before settlement. No funds transfer. | POST /v1/transactions/{id}/cancel with type cancel on an authorized or captured transaction before batch closure. |
settled | Funds have been transferred from the person's account to the merchant's account. | The batch containing the transaction closes and clears through the processor network. |
refunded | Funds have been returned to the person after settlement. | POST /v1/transactions/{id}/cancel with type refund on a settled transaction. |
Card transactions follow a two-phase process: authorization and settlement.
When you create a transaction, the processor communicates with the card network and issuing bank to verify funds and approve the payment. A successful authorization places a hold on the person's account for the approved amount.
At this point, the transaction is either authorized or declined.
Authorized transactions accumulate in a batch. When the batch closes (either on schedule or manually), the processor submits the batch to the card network for clearing, and funds transfer from the issuing bank to the merchant's acquiring bank.
For more information, see About batch settlement.
The lifecycle differs depending on whether you use a one-step sale or a two-step authorization.
| Flow | Steps | Use case |
|---|---|---|
| One-step (sale) | POST /v1/transactions with type sale → authorized → settled | Immediate fulfillment (digital goods, in-person retail) |
| Two-step (auth + capture) | POST /v1/transactions with type auth → POST /v1/transactions/{id}/capture → settled | Delayed fulfillment (shipping, pre-orders) |
For a detailed comparison, see About sale vs. authorization.
ACH transactions follow a different timeline because the Automated Clearing House (ACH) network processes in batches rather than in real time.
| Event | Timeline |
|---|---|
| Transaction submitted | Immediate API response with authorized state |
| Batch sent to ACH network | Next business day |
| Funds settled | 2–3 business days |
| Returns possible | Up to 60 days |
ACH transactions can be returned after settlement (for example, due to insufficient funds or a closed account). For more information, see About ACH/bank account payments.
The action you take to reverse a transaction depends on its current state.
| Current state | Action | Result |
|---|---|---|
authorized or captured (before batch closure) | Cancel (void) | Transaction moves to canceled. No funds transfer. |
settled | Refund | A new credit transaction returns funds to the person. |
For more information, see About cancels and refunds.
Retrieve the current state of any transaction with GET /v1/transactions/{id}. The transaction_state field reflects the current lifecycle position.
curl -X GET \
https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-ID \
-H "APIKEY: YOUR-API-KEY"Replace TRANSACTION-ID with the transaction identifier from the original response.