Skip to main content

Transactions

The Transactions API lets you read payments captured by your store and issue refunds against them.

Overview​

The Transactions API provides endpoints to:

A transaction is a captured payment — a record exists only once a payment has settled, so every transaction has a settlement date. Reads are otherwise read-only; the only write is issuing a refund.

Refund state​

There is no pending / failed / succeeded status on a transaction (a transaction record is itself a successful payment). Instead, each transaction exposes a derived refund state computed from how much of it has been refunded:

Refund stateMeaning
noneNo refunds have completed
partialRefunded less than the total
fullRefunded the whole total (or more)

Only completed refunds count toward the refund state and refunded_amount. A pending refund leaves both unchanged until it completes.

The list endpoint's status filter accepts these values.

Refunds are recorded asynchronously​

Issuing a refund initiates it at the payment provider and returns 202 Accepted. The refund record, its tax split, and the customer notification are written later when the provider confirms the refund via webhook. See Issue a refund for details.

Pending refunds​

A refund the payment provider has accepted can take time to complete — for example, while your balance with the provider cannot cover it yet, or on bank-based payment methods that return funds more slowly. Until it completes, the refund is pending. A pending refund:

  • is not counted in refunded_amount or refund_state, and does not appear in the refunds include;
  • is subtracted from remaining_refundable, so the same amount cannot be refunded twice.

While a refund is pending, remaining_refundable is therefore lower than total - refunded_amount. It can be 0 on a transaction whose refund_state is still none. A new refund request is checked against this lower value, so it returns 422 if it asks for more than is left (see Refund Cannot Be Issued).

When the pending refund completes, its amount moves into refunded_amount and the refund appears in refunds. When it fails, it no longer reduces remaining_refundable, and its amount can be refunded again.