Transfer funds between you and your sub-entity Early access

Last updated: 6th May 2022

While managing the sub-entities on your platform, those on the full account type may need to transfer money to recoup funds from a seller, return money from a refund or to make up the difference when running a promotion.

Refunds and chargebacks

Funds from all customer refunds and chargebacks will be deducted from your currency account (the platform). Use this transfer functionality to return sub-entity funds as appropriate.

Before you begin

To start making transfers, you must be on the Full account type.
Onboard your sub-entities to our Platforms solution.
Make the first payment on behalf of your sub-entity.
Sign up to receive a webhook notification for transfer_status_changed.

Transfers can only be requested between different entity levels. Transfers between 2 sub-entities will not be accepted.

Request a transfer through the Dashboard

From the Dashboard home page, go to Sub-entities, then select a sub-entity from the list. This will open the Sub-entity details page.

The Sub-entity details page displays the sub-entity balance and a list of recent transfers.

To request a new transfer:

Select Transfer. This will take you to a full screen
Select whether you would like to transfer funds to or from the sub-entity
Select either the source or destination of the transfer from the drop-down
Specify the amount to transfer
Select a reason for the transfer, and enter an optional reference
Select Transfer funds

Request a transfer using the API

To get a detailed view of all required and optional fields, see our API reference.

Notice that the sub-domain – transfers.checkout.com – is slightly different to Checkout.com's other endpoints.

post

https://transfers.checkout.com/transfers

Request example

{
  "reference": "superhero1234",
  "transfer_type": "commission",
  "source": {
    "id": "ent_azsiyswl7bwe2ynjzujy7lcjca",
    "amount": 100
  },
  "destination": {
    "id": "ent_w4jelhppmfiufdnatam37wrfc4"
  }
}

Response example

{
  "id": "tra_y3oqhf46pyzuxjbcn2giaqnb4",
  "status": "pending",
  "_links": {
    "self": "https://transfers.checkout.com/transfers/tra_y3oqhf46pyzuxjbcn2giaqnb4"
  }
}

The state of the payment is pending until the transfer is confirmed. Use the Balances API to check the funds have gone to the requested entity.

Retrieve a transfer

To get a detailed view of all required and optional fields, see our API reference.

get

https://transfers.checkout.com/transfers/{id}

Response example

{
  "id": "tra_y3oqhf46pyzuxjbcn2giaqnb4",
  "reference": "superhero1234",
  "status": "pending",
  "transfer_type": "commission",
  "requested_on": "2021-12-15T09:15:02.3845763Z",
  "source": {
    "entity_id": "ent_azsiyswl7bwe2ynjzujy7lcjca",
    "amount": 100,
    "currency": "GBP"
  },
  "destination": {
    "entity_id": "ent_bqik7gxoavwhmy3ot6kvmbx6py"
  },
  "_links": {
    "self": "https://transfers.checkout.com/transfers/tra_y3oqhf46pyzuxjbcn2giaqnb4"
  }
}

Transfer statuses

For visibility on what's going on with your transfers, we have created a webhook event called transfer_status_changed. It triggers every time the status of a transfer has changed.

There are 3 statuses:

Pending: Triggered when you create the transfer request
Completed: Triggered when the transfer has been completed successfully
Rejected: Triggered when the transfer was unsuccessful

To view the status of the transfer, view the data object, where you will be able to see the status field. See the following example webhook payloads.

Examples

{
  "id": "evt_htielsmgcwgejgqaunl4yb2pou",
  "type": "transfer_status_changed",
  "version": "1.0.0",
  "created_on": "2020-08-20T15:24:13.8431084Z",
  "data": {
    "transfer_id": "tra_6u262tenielmkj4cb5swqna6sy",
    "status": "Pending",
    "reference": "This is a reference"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/workflows/events/evt_htielsmgcwgejgqaunl4yb2pou"
    }
  }
}