Skip to main content

Chargebacks

Introduction#

info

This section is only relevant for Unit clients who offer their customers the ability to collect card payments using a third party payment processor (e.g. Stripe, Checkout, Adyen).

When collecting card payments in exchange for goods or services, the seller may occasionally face a Chargeback. Chargebacks are instructions from the payment processor to the seller, to returns the funds for a certain purchase, after the payer has submitted a successful dispute, and they must be honored.

If the funds collected are held at a bank account the processor has access to, they will pull the chargeback funds directly from that account. However, if the funds are held at another financial institution (e.g. on the Unit platform), the funds may need to be taken from the seller account, and returned back to the processor (or netted out from the next payout to the merchant).

In order to pull the funds from the seller's account, you should use the Chargeback resource. Creating a Chargeback initiates a transfer of funds from the merchant's account to a counterparty account of your choice, from which they may be sent to the payment processor and eventually to the end customer who raised the dispute. Chargeback creation should always succeed, even if the funds are not available in the seller's account, and may result in a negative balance. A Chargeback Transaction will be generated in both the seller's account and the counterparty account.

note

The ability to create Chargebacks is not enabled by default. To enable it, please contact Unit support and provide the details of your counterparty account.

Create Chargeback#

Creates a chargeback from an Account to a Counterparty.

VerbPOST
Urlhttps://api.s.api.unit.sh/chargebacks
Required Scopechargebacks-write
Timeout (Seconds)5

Attributes#

NameTypeDescription
amountintegerThe amount (in cents) to charge the account and credit the counterparty.
descriptionstringDescription of the chargeback (maximum of 50 characters).
tagsobjectOptional. See Tags.
idempotencyKeystringOptional. See Idempotency.

Relationships#

NameTypeDescription
accountJSON:API RelationshipThe Deposit Account the funds will be debited from.
counterpartyAccountJSON:API RelationshipThe account that will receive the funds.
curl -X POST 'https://api.s.unit.sh/chargebacks' \--header 'Content-Type: application/vnd.api+json' \--header 'Authorization: Bearer $Token' \--data-raw '{  "data":{    "type":"chargeback",    "attributes": {      "amount": 50,      "description": "Chargeback for dispute #1337",      "tags": {        "internalId": "abc1345"      }    },    "relationships": {      "account": {        "data": {          "type": "account",          "id": "10002"        }      },      "counterpartyAccount": {        "data": {          "type": "account",          "id": "10004"        }      }    }  }}'

Response#

Response is a JSON:API document.

201 CREATED#

{  "data":{    "type":"chargeback",    "attributes": {      "amount": 50,      "description": "Chargeback for dispute #1337",      "tags": {        "internalId": "abc1345"      }    },    "relationships": {      "account": {        "data": {          "type": "account",          "id": "10002"        }      },      "counterpartyAccount": {        "data": {          "type": "account",          "id": "10004"        }      }    }  }}

Get by Id#

Get a chargeback by id.

VerbGET
Urlhttps://api.s.unit.sh/chargeback/{id}
Required Scopechargebacks
Timeout (Seconds)5
NameTypeDefaultDescription
includestring(empty)Optional. A comma-separated list of related resources to include in the response. Related resources include: customer, account, transaction. See Getting Related Resources
curl GET 'https://api.s.unit.sh/chargebacks/2' \--header 'Authorization: Bearer $Token

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataChargebackChargeback resource.
includedArray of DepositAccount or Customer or TransactionArray of resources requested by the include query parameter.

List#

List chargeback resources. Filtering, paging and sorting can be applied.

VerbGET
Urlhttps://api.s.unit.sh/chargebacks
Required Scopechargebacks
Timeout (Seconds)5

Query Parameters#

NameTypeDefaultDescription
page[limit]integer100Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]integer0Number of resources to skip. See Pagination.
filter[accountId]string(empty)Optional. Filters the results by the specified account id.
filter[customerId]string(empty)Optional. Filters the results by the specified customer id.
filter[tags]Tags (JSON)(empty)Optional. Filter Chargebacks by Tags.
filter[since]RFC3339 Date string(empty)Optional. Filters the Chargebacks that occurred after the specified date. e.g. 2020-01-13T16:01:19.346Z
filter[until]RFC3339 Date string(empty)Optional. Filters the Chargebacks that occurred before the specified date. e.g. 2020-01-02T20:06:23.486Z
sortstringsort=-createdAtOptional. Leave empty or provide sort=createdAt for ascending order. Provide sort=-createdAt (leading minus sign) for descending order.
includestring(empty)Optional. A comma-separated list of related resources to include in the response. Related resources include: customer, account, transaction. See Getting Related Resources
curl -X GET 'https://api.s.unit.sh/chargebacks?page[limit]=20&page[offset]=10' \-H "Authorization: Bearer $Token"

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataArray of ChargebackArray of chargeback resources.
includedArray of DepositAccount or Customer or TransactionArray of resources requested by the include query parameter.
{  "data": [    {      "type": "chargeback",      "id": "1",      "attributes": {        "createdAt": "2022-03-24T17:36:47.638Z",        "amount": 15000,        "description": "Chargeback for payment #112",        "tags": {          "internalId": "abc14545"        }      },      "relationships": {        "account": {          "data": {            "type": "account",            "id": "10046"          }        },        "customer": {          "data": {            "type": "customer",            "id": "10707"          }        },        "counterpartyAccount": {          "data": {            "type": "account",            "id": "10305"          }        },        "transaction": {          "data": {            "type": "transaction",            "id": "10024"          }        }      }    },    {      "type": "chargeback",      "id": "2",      "attributes": {        "createdAt": "2022-03-24T17:36:47.638Z",        "amount": 5000,        "description": "Chargeback for dispute #1337",        "tags": {          "internalId": "abc1345"        }      },      "relationships": {        "account": {          "data": {            "type": "account",            "id": "10006"          }        },        "customer": {          "data": {            "type": "customer",            "id": "10007"          }        },        "counterpartyAccount": {          "data": {            "type": "account",            "id": "10005"          }        },        "transaction": {          "data": {            "type": "transaction",            "id": "10025"          }        }      }    }  ]}