Third Party Card Payment Processors

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.

Verb	`POST`
Url	`https://api.s.api.unit.sh/chargebacks`
Required Scope	`chargebacks-write`
Timeout (Seconds)	`5`

Attributes#

Name	Type	Description
amount	integer	The amount (in cents) to charge the account and credit the counterparty.
description	string	Description of the chargeback (maximum of 50 characters).
tags	object	Optional. See Tags.
idempotencyKey	string	Optional. See Idempotency.

Relationships#

Name	Type	Description
account	JSON:API Relationship	The Deposit Account the funds will be debited from.
counterpartyAccount	JSON:API Relationship	The 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.

Verb	`GET`
Url	`https://api.s.unit.sh/chargeback/{id}`
Required Scope	`chargebacks`
Timeout (Seconds)	`5`

Name	Type	Default	Description
include	string	(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#

Field	Type	Description
data	Chargeback	Chargeback resource.
included	Array of DepositAccount or Customer or Transaction	Array of resources requested by the `include` query parameter.

List#

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

Verb	`GET`
Url	`https://api.s.unit.sh/chargebacks`
Required Scope	`chargebacks`
Timeout (Seconds)	`5`

Query Parameters#

Name	Type	Default	Description
page[limit]	integer	100	Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]	integer	0	Number 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`
sort	string	`sort=-createdAt`	Optional. Leave empty or provide `sort=createdAt` for ascending order. Provide `sort=-createdAt` (leading minus sign) for descending order.
include	string	(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#

Field	Type	Description
data	Array of Chargeback	Array of chargeback resources.
included	Array of DepositAccount or Customer or Transaction	Array 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"          }        }      }    }  ]}