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"
          }
        }
      }
    }
  ]
}