A transaction is not finished when the response arrives. It gets authorized, possibly captured, gathered into a batch, settled, and — for ACH — it can still be returned days later.
Knowing which stage a transaction is in tells you what you can still do to it. Most of the rules on this page reduce to one question: has it settled yet?
| Stage | How you know | What you can do |
|---|---|---|
| Authorized | result is APPROVED | Capture it, or void it |
| Awaiting capture | type is AUTH and no capture references it | Capture, partially capture, or void |
| In a batch | batch_id is not null | Void it, until the batch closes |
| Settled | is_settled is true | Refund it |
| Returned | is_returned is true | Nothing. ACH only |
batch_id is null until the transaction reaches a batch, which happens when the settlement request gets to the processor rather than at the moment you are approved. A null batch_id on a fresh sale is normal.
This is the part that surprises people coming from other gateways.
A capture does not update the authorization. It creates a new transaction with its own id, a type of CAPTURE, and a reference_transaction_id pointing back at the authorization. The same is true of a cancel and a refund.
So a single payment can be several records:
TRANSACTION-…A type: AUTH reference_transaction_id: null
TRANSACTION-…B type: CAPTURE reference_transaction_id: TRANSACTION-…A
TRANSACTION-…C type: REFUND reference_transaction_id: TRANSACTION-…BWhen you reconcile, follow reference_transaction_id rather than expecting one row per payment.
They are not interchangeable, and picking the wrong one is a common source of 400s and empty report results.
| Where | Values |
|---|---|
| Creating a transaction | SALE, AUTH, PAYOUT |
| On a response, and on the report filter | SALE, AUTH, INCREMENTAL_AUTH, PAYOUT, REFUND, CANCEL, CAPTURE |
| As the discriminator on a cancel or refund body | VOID, REFUND |
A voided payment comes back as CANCEL, never VOID. VOID is the word you send; CANCEL is the word you read. Filtering a report on VOID returns a server error — see Find and report on transactions.
INCREMENTAL_AUTH appears only on responses. There is no way to create one through the public API.
A card decline arrives in the response. An ACH return does not — it can show up days after settlement, when the receiving bank rejects the entry.
is_returned carries it, and it is worth reading alongside is_settled rather than instead of it, because a returned transaction has usually settled first. Accept an ACH payment covers the return fields and their quirks.
There are no webhooks, so finding out means polling the reporting endpoints.