Chargebacks
A chargeback is a payment dispute raised by the cardholder's bank against an order. Vatly records it (and any later reversal) so you can suspend access and reconcile the reversed VAT.
For all fields and options, see the Chargebacks API reference. The OpenAPI spec is also available for tooling.
The Chargeback resource
| Name | Type | Description |
|---|---|---|
id | string | Unique identifier (chargeback_…). |
customerId | string | The customer who disputed. |
originalOrderId | string | The order being disputed. |
status | string | Dispute status. |
reason | string | null | Reason given, if any. |
total | Money | Gross amount disputed (incl. tax). |
subtotal | Money | Net amount disputed (excl. tax). |
taxSummary | array | Per-rate VAT breakdown. |
testmode | boolean | Whether this is a test chargeback. |
Retrieve a chargeback
GET /v1/chargebacks/{chargebackId}
const chargeback = await vatly.chargebacks.get("chargeback_abc123");
List chargebacks
GET /v1/chargebacks
const page = await vatly.chargebacks.list({ limit: 25 });
for await (const chargeback of vatly.chargebacks.listAll()) {
// ...
}
Chargebacks for a specific order are also available via
vatly.orders.listChargebacks(orderId) and
vatly.orders.getChargeback(orderId, chargebackId) — see Orders.
Reacting to disputes
Listen for the order.chargeback_received and order.chargeback_reversed
webhooks. The delivery's entityId is the order id and object is the full
Chargeback (incl. the tax breakdown), so you can suspend access and reconcile
the reversed VAT without a follow-up call.