Refunds
Full and partial refunds for card and ACH payments.
A refund returns funds to a customer after a payment has settled. Before settlement, cancel with VOID or AUTH_REVERSAL instead — see Auth Reversal vs. Void. The cutoff is the parent reaching SETTLED, not a wall-clock window.
Card refunds
curl -X POST https://api.cresoracommerce.ai/api/v1/transactions \
-H "Authorization: Bearer csk_ab12cd34_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: idem_$(uuidgen)" \
-d '{ "type": "REFUND", "merchant_id": "0190a1b2-c3d4-7e5f-8901-23456789abcd", "parent_transaction_id": "0190d8a1-2b3c-7d4e-9f12-7a8b9c0d1e2f", "refund_reason": "customer_requested" }'curl -X POST https://api.cresoracommerce.ai/api/v1/transactions \
-H "Authorization: Bearer csk_ab12cd34_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: idem_$(uuidgen)" \
-d '{ "type": "PARTIAL_REFUND", "merchant_id": "0190a1b2-c3d4-7e5f-8901-23456789abcd", "parent_transaction_id": "0190d8a1-2b3c-7d4e-9f12-7a8b9c0d1e2f", "amount": "50.00", "refund_reason": "customer_requested" }'refund_reason is required and structured: overpayment, service_not_rendered, insurance_adjustment, customer_requested, or other_with_note (pair the last with a refund_note, max 280 characters).
Refund rules
| Rule | Detail |
|---|---|
| Parent state | Must be SETTLED — a pre-settlement refund is rejected; use VOID/AUTH_REVERSAL |
Full refund (REFUND) | amount is ignored — the platform derives parent amount − cumulative refunds |
Partial refund (PARTIAL_REFUND) | amount required, up to the remaining refundable capacity |
| Multiple partials | Allowed until cumulative equals the original amount |
| Settlement timing | Credit appears on the cardholder statement in 3–7 business days |
Refund response
The refund is a transaction — there is no separate refund resource, no ref_ id, and no pending/succeeded lifecycle. The response is a normal transaction object: a transaction_id (UUID), type: REFUND or PARTIAL_REFUND, its own state, the amount, and the parent_transaction_id linking it to the original payment.
The parent is where refund progress lives: it transitions to PARTIALLY_REFUNDED (re-entrant across multiple partials) and to REFUNDED once cumulative refunds equal the original amount. Track the parent's state for "how much of this payment is still refundable".
ACH refunds
For ACH payments, a refund creates a new credit ACH entry — it doesn't reverse the original debit. The customer receives the credit 1–3 business days after submission.
curl -X POST https://api.cresoracommerce.ai/api/v1/transactions \
-H "Authorization: Bearer csk_ab12cd34_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: idem_$(uuidgen)" \
-d '{ "type": "ACH_REFUND", "merchant_id": "0190a1b2-c3d4-7e5f-8901-23456789abcd", "parent_transaction_id": "0190d8a1-2b3c-7d4e-9f12-7a8b9c0d1e2f", "refund_reason": "customer_requested" }'To correct an erroneous ACH entry, use type: "ACH_REVERSAL" instead — valid only within 5 banking days of settlement (nacha_reversal_window_expired past it) and requiring a structured reversal_reason (INCORRECT_AMOUNT, INCORRECT_ACCOUNT, DUPLICATE_ENTRY, INCORRECT_EAN). A reversal is a correction instrument, not a customer-refund instrument. See ACH Transactions →.
Webhook events
| Event | When |
|---|---|
transaction.refund_issued | The refund transaction is created |
transaction.refunded | The parent reaches fully refunded |
transaction.failed | Refund fails (rare — contact support). The event carries the failed transaction's type, so a failed refund is distinguishable from a failed sale. |