Refund a payment
Gives money back on a captured payment, in full or in part. Money moves back to the shopper's payment method and refund events fire. Secret and trusted tokens that may create refunds only; a limited token gets 403.
AuthorizationBearer <token>A secret, trusted or limited token. See Authentication.
payment_id*stringThe id of the payment.
expand?stringComma-separated child objects to return in full instead of as a URL, for example customer,payments. Use dot notation for nested objects (items.product), up to four levels deep. A single object takes up to 12 paths; a list takes up to 2, applied to every item. Extra paths are dropped without an error. See Expanding objects.
formatted?booleanWhen true, the object also has a formatted child with amounts and dates as display text in the shopper's language and currency (for example $19.99 or November 7, 2026). The default is false. See Localized formatting.
falseapplication/json- body
What to refund. Send no body, or {}, to refund everything that has not been refunded yet (a full refund). For a partial refund send exactly one of total, tax, items or shipping; items and shipping may be sent together. The other amounts are worked out for you. subtotal is never accepted. items works when you refund an order or an invoice, or a payment that belongs to one. A payment with no order or invoice ignores items, so a body with only items refunds that payment in full.
total?numberThe amount to give back, with tax, in the payment currency. The tax part is worked out for you. This plus earlier refunds cannot be more than what was paid. Required when is_chargeback is true.
0 < valuetax?numberRefund only tax, for example when tax was charged by mistake. Cannot be sent with total, items or shipping.
0 < valueshipping?numberThe shipping amount to give back, with tax, in the payment currency. Up to the shipping not refunded yet. May be sent with items.
0 < valueitems?array<>The items to refund, by item_id and quantity. Only for an order, an invoice, or a payment that belongs to one.
1 <= itemsreason?stringWhy you are refunding. Use one of the reasons from GET /refunds/options to keep reports tidy.
comments?stringYour own notes about the refund.
length <= 1024reference?stringYour own reference for the refund. You can filter lists by it.
length <= 100meta?|Your own data for the refund, a string or an object. At most 2048 characters once serialized.
payment_method?Send {"type": "customer_account_balance"} to give the money to the customer's store credit instead of back to the card or wallet they paid with. Leave it out to refund the original payment method.
is_chargeback?booleanSet to true to record a chargeback the bank already took. No money moves. Needs total. Only used on accounts on the agent model (or when Comecero staff send it); otherwise it is ignored without an error and the refund is real: money goes back. On a gateway that Comecero owns, only Comecero staff may send it (400). An order with more than one successful payment must take it on the payment instead. Not allowed when the payment was made from store credit.
record_only?booleanSet to true to write down a refund you paid back some other way. No money moves. Needs record_only_memo. Same limits as is_chargeback.
record_only_memo?stringHow a record-only refund was paid back, at least 5 characters. Required when record_only is true.
5 <= lengthThe refund.
application/json- response
Money given back on one payment, or a chargeback or a record-only refund written down against it. Fields marked "not for limited tokens" are left out when a limited token reads the refund. Links to other objects only appear when the token may read that object.
object*"refund"The object type. Always refund.
"refund"url*stringThe full URL of the refund.
urirefund_id*stringThe refund id.
account_id*stringThe account the refund belongs to.
success*booleanTrue when the refund is completed or pending.
status*stringcompleted once the money is back with the customer, pending while the payment provider is still working on it, failed when it was refused.
"pending""completed""failed"reference*|Your own reference for the refund, up to 100 characters.
date_created*stringWhen the refund was created.
date-timedate_modified*stringWhen the refund was last changed.
date-timedate_completed*|When the refund completed. Null until then.
date-timetest*booleanTrue for a test refund.
currency*stringThe currency of the refund, the payment currency (ISO 4217).
subtotal*numberThe amount refunded without shipping and tax, in currency.
shipping*numberThe shipping refunded without tax, in currency.
tax*numberThe tax refunded, in currency.
total*numberThe whole amount refunded, in currency.
reason*|Why the refund was made. See GET /refunds/options for the reasons your account lists.
apply_to_balance*booleanTrue when the payment it refunds was applied to the customer account balance.
is_chargeback?booleanTrue when this records a chargeback (the bank took the money back) rather than a refund you made. Not for limited tokens.
record_only?booleanTrue when the refund was only written down and no money moved through the payment provider (for example you refunded by bank transfer, or the rest of a partial capture). Not for limited tokens.
record_only_memo?|How a record-only refund was really paid back. Not for limited tokens.
response_code?|The Comecero result code, for example OK or payment_declined. Not for limited tokens.
response_message?|The Comecero result message. Not for limited tokens.
gateway_transaction_id?|The payment provider's id for the refund. Not for limited tokens.
gateway_error_code?|The payment provider's own error code when the refund failed. Not for limited tokens.
gateway_error_message?|The payment provider's own error message when the refund failed. Not for limited tokens.
gateway?|A link to the gateway that processed the refund, or the gateway when you send expand=gateway. Only for tokens that may read gateways.
comments?|Your own notes about the refund. Not for limited tokens.
payment_method*||A link to the payment method the money went back to, or the payment method when you send expand=payment_method. Null for a record-only refund.
settlement_currency?stringThe currency the money settles to your account in. Not for limited tokens.
settlement_subtotal?numbersubtotal in the settlement currency. Not for limited tokens.
settlement_shipping?numbershipping in the settlement currency. Not for limited tokens.
settlement_tax?numbertax in the settlement currency. Not for limited tokens.
settlement_total?numbertotal in the settlement currency. Not for limited tokens.
fx_rate?numberThe exchange rate from currency to settlement_currency, taken from the payment. Not for limited tokens.
reporting_currency*|Your account's main reporting currency.
reporting_subtotal*numbersubtotal in the reporting currency.
reporting_shipping*numbershipping in the reporting currency.
reporting_tax*numbertax in the reporting currency.
reporting_total*numbertotal in the reporting currency.
reporting_fx_rate*numberThe rate from the settlement currency to the reporting currency.
reporting_alt_currency?stringYour account's second reporting currency. This and the other reporting_alt_ fields are only present when the account has one.
reporting_alt_subtotal?numbersubtotal in the second reporting currency.
reporting_alt_shipping?numbershipping in the second reporting currency.
reporting_alt_tax?numbertax in the second reporting currency.
reporting_alt_total?numbertotal in the second reporting currency.
reporting_alt_fx_rate?numberThe rate from the settlement currency to the second reporting currency.
items*|array<>|For a refund on an order or invoice that names items, a link to the refunded items, or the items when you send expand=items. Null when the refund has no items.
customer?|A link to the customer, or the customer when expanded.
order?||A link to the order, or the order when expanded. Null when the payment has no order.
payment?|A link to the payment refunded, or the payment when expanded.
invoice?||A link to the invoice, or the invoice when expanded. Null when the payment has no invoice.
fees?|A link to the fees on this refund, or the list when you send expand=fees on a single refund. Not for limited tokens.
fee_summary?|A link to the refund's fee summary, or the summary when expanded. Not for limited tokens.
commissions?|A link to the commissions on this refund, or the list when you send expand=commissions on a single refund. Not for limited tokens.
debug?stringA link to the payment provider's raw requests and responses. Only present for accounts on the agent model, and for Comecero staff.
urimeta*||Your own data for the refund, a string or an object.
formatted?The amounts and dates as display text. Only present when you send formatted=true.
curl -X POST 'https://api.comecero.com/api/v1/payments/string/refunds' \ -H 'Content-Type: application/json' \ -d '{}'{ "object": "refund", "url": "https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5", "refund_id": "0090374314462Rec3PffZ5", "account_id": "AB1234", "success": true, "status": "completed", "reference": null, "date_created": "2026-11-03T10:12:40Z", "date_modified": "2026-11-03T10:12:41Z", "date_completed": "2026-11-03T10:12:41Z", "test": true, "currency": "USD", "subtotal": 49.95, "shipping": 0, "tax": 0, "total": 49.95, "reason": "Customer request", "apply_to_balance": false, "is_chargeback": false, "record_only": false, "record_only_memo": null, "response_code": "OK", "response_message": "OK", "gateway_transaction_id": "re_test_3PffZ5", "gateway_error_code": null, "gateway_error_message": null, "gateway": "https://api.comecero.com/api/v1/gateways/0089584408915Gtf5AsdJ8", "comments": null, "payment_method": "https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/payment_method", "settlement_currency": "USD", "settlement_subtotal": 49.95, "settlement_shipping": 0, "settlement_tax": 0, "settlement_total": 49.95, "fx_rate": 1, "reporting_currency": "USD", "reporting_subtotal": 49.95, "reporting_shipping": 0, "reporting_tax": 0, "reporting_total": 49.95, "reporting_fx_rate": 1, "items": "https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/items", "customer": "https://api.comecero.com/api/v1/customers/0093717976099CuAiEBXu4", "order": "https://api.comecero.com/api/v1/orders/7393-GMRFY-954", "payment": "https://api.comecero.com/api/v1/payments/0093717991362PyRYN1qc6", "invoice": null, "fees": "https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fees", "fee_summary": "https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/fee_summary", "commissions": "https://api.comecero.com/api/v1/refunds/0090374314462Rec3PffZ5/commissions", "meta": null}List payment refunds GET
Lists the refunds and chargebacks of a payment. An offset-based list. `sort_by` takes `date_created` (the default), `date_modified` or `date_completed`. Any token type may call it; a limited token only for a payment it is bound to.
Retrieve payment response data GET
Returns what the gateway sent back for the payment, by payment method type. For an `initiated` payment it holds the shopper's next step: a `redirect_url` (PayPal approval, or a 3-D Secure page), a `next_action` for a Comecero Express Payments 3-D Secure check on your own page, or the Stripe.js values for a `stripe` payment. For a card it holds the address and security code results (not for a limited token). Any token type may call it; a limited token only for a payment it is bound to.