Api Reference
Chargebacks
On this page, we'll dive into the different chargeback endpoints you can use to query chargebacks programmatically.
The chargeback model
The chargeback model contains all the information about payment disputes, including the disputed amount, settlement amount, reason, and related order information.
Chargebacks are created automatically when a payment provider initiates a dispute. They are read-only resources.
Properties
| Name | Type | Description |
|---|---|---|
id | string | Unique identifier for the chargeback (starts with chb_). |
resource | string | The resource type. Always chargeback. |
merchantId | string | ID of the merchant. |
testmode | boolean | Whether this chargeback is in test mode. |
amount | Money | Amount of the chargeback. A Money object with value (decimal string) and currency (ISO 4217 code). |
settlementAmount | Money | Amount that was deducted from the merchant's settlement. May differ from amount due to currency conversion or fees. |
reason | string | Reason code or description for the chargeback. Common reasons include fraud, product_not_received, product_unacceptable, duplicate, or subscription_canceled. |
originalOrderId | string | ID of the original order that was charged back. |
orderId | string | null | ID of the credit note order created for this chargeback. Only present after the chargeback is processed. |
createdAt | string | When this chargeback was created (ISO 8601 format). |
links | object | HATEOAS links to related resources. Contains self, originalOrder, and optionally order (the credit note). |
List all chargebacks
GET /v1/chargebacks
This endpoint allows you to retrieve a paginated list of all chargebacks across all orders.
Optional parameters
| Name | Type | Description |
|---|---|---|
limit | integer | The number of chargebacks to return (default: 10, max: 100). |
startingAfter | string | A cursor for use in pagination. Returns results after this chargeback ID. |
endingBefore | string | A cursor for use in pagination. Returns results before this chargeback ID. |
curl -G https://api.vatly.com/v1/chargebacks \
-H "Authorization: Bearer live_your_api_key_here" \
-d limit=10
$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');
$chargebacks = $vatly->chargebacks->page();
{
"data": [
{
"id": "chb_abc123def456",
"resource": "chargeback",
"merchantId": "mer_abc123",
"testmode": false,
"amount": {
"value": "99.99",
"currency": "EUR"
},
"settlementAmount": {
"value": "114.99",
"currency": "EUR"
},
"reason": "fraud",
"originalOrderId": "ord_original123",
"orderId": "ord_chargeback123",
"createdAt": "2024-01-15T10:30:00Z",
"links": {
"self": {
"href": "https://api.vatly.com/v1/chargebacks/chb_abc123def456",
"type": "application/json"
},
"originalOrder": {
"href": "https://api.vatly.com/v1/orders/ord_original123",
"type": "application/json"
},
"order": {
"href": "https://api.vatly.com/v1/orders/ord_chargeback123",
"type": "application/json"
}
}
}
],
"links": {
"self": {
"href": "https://api.vatly.com/v1/chargebacks?limit=10",
"type": "application/json"
},
"next": null,
"prev": null
},
"count": 1
}
Get a chargeback
GET /v1/chargebacks/:chargebackId
This endpoint allows you to retrieve a specific chargeback by its ID.
Parameters
| Name | Type | Description |
|---|---|---|
chargebackId | string | The unique identifier of the chargeback. |
curl https://api.vatly.com/v1/chargebacks/chb_abc123def456 \
-H "Authorization: Bearer live_your_api_key_here"
$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');
$chargeback = $vatly->chargebacks->get('chb_abc123def456');
{
"id": "chb_abc123def456",
"resource": "chargeback",
"merchantId": "mer_abc123",
"testmode": false,
"amount": {
"value": "99.99",
"currency": "EUR"
},
"settlementAmount": {
"value": "114.99",
"currency": "EUR"
},
"reason": "fraud",
"originalOrderId": "ord_original123",
"orderId": "ord_chargeback123",
"createdAt": "2024-01-15T10:30:00Z",
"links": {
"self": {
"href": "https://api.vatly.com/v1/chargebacks/chb_abc123def456",
"type": "application/json"
},
"originalOrder": {
"href": "https://api.vatly.com/v1/orders/ord_original123",
"type": "application/json"
},
"order": {
"href": "https://api.vatly.com/v1/orders/ord_chargeback123",
"type": "application/json"
}
}
}
List order chargebacks
GET /v1/orders/:orderId/chargebacks
This endpoint allows you to retrieve a paginated list of chargebacks for a specific order.
Parameters
| Name | Type | Description |
|---|---|---|
orderId | string | The unique identifier of the order. |
limit | integer | The number of chargebacks to return (default: 10, max: 100). |
startingAfter | string | A cursor for use in pagination. Returns results after this chargeback ID. |
endingBefore | string | A cursor for use in pagination. Returns results before this chargeback ID. |
curl -G https://api.vatly.com/v1/orders/ord_original123/chargebacks \
-H "Authorization: Bearer live_your_api_key_here" \
-d limit=10
$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');
$chargebacks = $vatly->orders->chargebacks('ord_original123')->page();
{
"data": [
{
"id": "chb_abc123def456",
"resource": "chargeback",
"merchantId": "mer_abc123",
"testmode": false,
"amount": {
"value": "99.99",
"currency": "EUR"
},
"settlementAmount": {
"value": "114.99",
"currency": "EUR"
},
"reason": "fraud",
"originalOrderId": "ord_original123",
"orderId": "ord_chargeback123",
"createdAt": "2024-01-15T10:30:00Z",
"links": {
"self": {
"href": "https://api.vatly.com/v1/chargebacks/chb_abc123def456",
"type": "application/json"
},
"originalOrder": {
"href": "https://api.vatly.com/v1/orders/ord_original123",
"type": "application/json"
},
"order": {
"href": "https://api.vatly.com/v1/orders/ord_chargeback123",
"type": "application/json"
}
}
}
],
"links": {
"self": {
"href": "https://api.vatly.com/v1/orders/ord_original123/chargebacks?limit=10",
"type": "application/json"
},
"next": null,
"prev": null
},
"count": 1
}
Get an order chargeback
GET /v1/orders/:orderId/chargebacks/:chargebackId
This endpoint allows you to retrieve a specific chargeback within an order context.
Parameters
| Name | Type | Description |
|---|---|---|
orderId | string | The unique identifier of the order. |
chargebackId | string | The unique identifier of the chargeback. |
curl https://api.vatly.com/v1/orders/ord_original123/chargebacks/chb_abc123def456 \
-H "Authorization: Bearer live_your_api_key_here"
$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');
$chargeback = $vatly->orders->chargebacks('ord_original123')->get('chb_abc123def456');
{
"id": "chb_abc123def456",
"resource": "chargeback",
"merchantId": "mer_abc123",
"testmode": false,
"amount": {
"value": "99.99",
"currency": "EUR"
},
"settlementAmount": {
"value": "114.99",
"currency": "EUR"
},
"reason": "fraud",
"originalOrderId": "ord_original123",
"orderId": "ord_chargeback123",
"createdAt": "2024-01-15T10:30:00Z",
"links": {
"self": {
"href": "https://api.vatly.com/v1/chargebacks/chb_abc123def456",
"type": "application/json"
},
"originalOrder": {
"href": "https://api.vatly.com/v1/orders/ord_original123",
"type": "application/json"
},
"order": {
"href": "https://api.vatly.com/v1/orders/ord_chargeback123",
"type": "application/json"
}
}
}