About cancels and refunds

Cancels vs. refunds

Both cancels and refunds reverse a transaction, but they apply at different stages of the transaction lifecycle.

	Cancel (void)	Refund
When	Before batch settlement	After batch settlement
Transaction state requirement	`authorized` or `captured`	`settled`
Fund movement	No funds transferred — the hold is released	Funds returned from merchant to person
Speed	Immediate release of held funds	5–10 business days for person to see credit
API type value	`cancel`	`refund`
Endpoint	`POST /v1/transactions/{id}/cancel`	`POST /v1/transactions/{id}/cancel`

When to cancel

Cancel a transaction when you need to reverse it before the settlement batch closes. Canceling releases the hold on the person's funds immediately without any funds transferring between accounts.

Common cancel scenarios

Person changes their mind before the order ships
Duplicate transaction detected
Authorization was placed but the item is out of stock
Incorrect amount authorized

Cancel request

Send POST /v1/transactions/{id}/cancel with the cancel type and amount.

{
  "type": "cancel",
  "amount": 15000
}

Replace {id} with the transaction ID from the original authorization or sale.

Cancel response

{
  "id": "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y",
  "object": "transaction",
  "type": "cancel",
  "transaction_state": "canceled",
  "response_status": "Approved",
  "response_code": "00",
  "response_message": "The API request is approved.",
  "correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

The transaction_state changes to canceled.

When to refund

Refund a transaction when the batch has already settled and funds have been transferred to the merchant's account. A refund creates a new credit transaction that returns funds to the person.

Common refund scenarios

Person returns a product after delivery
Service was not rendered as described
Billing dispute resolution

Full refund

To refund the full transaction amount, specify the original amount.

{
  "type": "refund",
  "amount": 15000
}

Partial refund

To refund part of the transaction, specify a lesser amount.

{
  "type": "refund",
  "amount": 5000
}

This refunds 50.00 US dollars (USD) of the original 150.00 US dollars transaction.

Refund response

{
  "id": "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y",
  "object": "transaction",
  "type": "refund",
  "transaction_state": "authorized",
  "response_status": "Approved",
  "response_code": "00",
  "response_message": "The API request is approved.",
  "correlation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
}

Refund settlement

A refund transaction goes through the same settlement process as a payment. The refund amount is deducted from the merchant's next settlement batch and credited back to the person's account.

ACH transaction cancels

ACH (bank account) transactions can also be canceled before settlement using the same endpoint.

Transaction type	Cancel type
`payment`	`cancel`
`payout`	`cancel`

ACH transactions that have already settled cannot be refunded through the API in the same way as card transactions. Instead, ACH reversals are subject to the ACH return process, which operates on the ACH network timeline (up to 60 days). For more information, see About ACH/bank account payments.

Timing considerations

The window for canceling vs. refunding depends on when the settlement batch closes.

Batch closure timing: Batches typically close at the end of each business day, but merchants can also close batches manually through PUT /v1/batches/status.
Cancel deadline: You must cancel before the batch containing the transaction closes.
Refund deadline: Refunds can be issued after settlement. Check with your processor for any time limits on issuing refunds.

Deciding between cancel and refund

Use this decision tree when handling a reversal request.

Retrieve the transaction with GET /v1/transactions/{id}.
Check the transaction_state field.
If the state is authorized or captured → cancel.
If the state is settled → refund.