Transfers

Transfers represent a movement of funds between/within Project accounts held in the trustshare API. They allow the movement of funds between projects and settlements.

You can use transfers to fix reconciliation mistakes by moving funds from one settlement to another. Or to batch payouts by moving funds from a settlement into a project balance to make a larger Outbound possible.

Inter-project vs. within-project

Inter-project transfers can be made between different project accounts held in the same currency. Where-as within-project transfers can be made between a project's balance and it's settlements. An associated Outbound and Inbound will only be created for an inter-project transfer as there is physical movement of funds.

See how to create a transfer

The transfer model

The transfer object provides a representation of an inter-project or within-project transfer in the trustshare API, include associated Projects, Settlements, Inbounds, and Outbounds.

Properties

Name
id
Type
string
Description
The unique ID of the transfer.
A string in the format: transfer_[0-9a-z].
Name
created_at
Type
string
Description
The date the transfer was created.
Name
updated_at
Type
string
Description
The date the transfer was last updated.
Name
type
Type
enum
Description
fee
The type of transfer.
Name
subtype
Type
enum
Description
buyer seller
The subtype of transfer.
Name
status
Type
enum
Description
awaiting_funds executing executed failed cancelled scheduled
The status of the transfer.
Name
amount
Type
integer
Description
The amount of the transfer.
Name
from
Type
object
Description
Show moreless
The object describing the settlement or project originatig the funds being transfered.
Name
project_id
Type
string
Description
The unique ID of the project originating the funds being transfered.
Name
settlement_id
Type
string
Description
The unique ID of the settlement originating the funds being transfered.
The object describing the settlement or project originatig the funds being transfered.
Name
to
Type
object
Description
Show moreless
The object describing the target project of the transfer.
Name
project_id
Type
string
Description
The unique ID of the project originating the funds being transfered.
Name
settlement_id
Type
string
Description
The unique ID of the settlement originating the funds being transfered.
The object describing the target project of the transfer.
Name
inbound_id
Type
string
Description
The unique ID of the inbound that describes funds entering the target project as a result of this transfer.
Name
outbound_id
Type
string
Description
The unique ID of the outbound that describes funds leaving the source project as a result of this transfer.
Name
release_at
Type
string
Description
The date that describes when the funds will be automatically transfered.
Name
metadata
Type
object
Description
The metadata that was provided at the creation of the transfer.

Example

{
  "id": "transfer_KKm0NR7sHg",
  "created_at": "2023-12-19T18:46:23.484Z",
  "updated_at": "2023-12-19T18:46:29.719Z",
  "status": "executed",
  "amount": 25000,
  "from": {
    "project_id": "project_KOXg0PqnFd",
    "settlement_id": null
  },
  "to": {
    "project_id": "project_wpVHxBljof",
    "settlement_id": null
  },
  "inbound_id": "inbound_JU7MwvMQFG",
  "outbound_id": "outbound_m6xIw5pM6H",
  "release_at": null,
  "metadata": {
    "foo": "can store my metadata"
  }
}

GET/v1/transfer/{id}

Get a Transfer

Retrieve an existing transfer.

Required attributes

Name
id
Type
string
Required
Required
Description
A unique ID of an existing transfer.
A string in the format: transfer_[0-9a-z]

Request

GET

/v1/transfer/transfer_KKm0NR7sHg

curl https://rest.trustshare.io/v1/transfer/transfer_KKm0NR7sHg \ 
  -H "Authorization: <private_key>"

POST/v1/transfers

Create Transfers

Used to create internal transfers between project accounts.

Required attributes

Name
transfers
Type
object[]
Required
Required
Description
Show moreless
A list of transfers to create.
Name
amount
Type
integer
Required
Required
Description
The amount to transfer in the currency's lowest denomination.
Name
fee_flat
Type
integer
Description
A flat fee to charge on successfully completing a Transfer.
Name
fee_percentage
Type
number
Description
A fee percentage to charge on successfully completing a Transfer. Fee percentages must be provided as a fraction, ie. 1.5% as 0.015.
Name
from
Type
object
Required
Required
Description
Show moreless
An object describing the settlement or project originatig the funds being transfered.
Name
project_id
Type
string
Description
A unique ID for the project originating the funds being transfered.
A string in the format project_[0-9a-z].
Name
settlement_id
Type
string
Description
A unique ID for the settlement originating the funds being transfered.
A string in the format settlement_[0-9a-z].
An object describing the settlement or project originatig the funds being transfered.
Name
to
Type
object
Required
Required
Description
Show moreless
An object describing the target project of the transfer.
Name
project_id
Type
string
Description
A unique ID for the project originating the funds being transfered.
A string in the format project_[0-9a-z].
Name
settlement_id
Type
string
Description
A unique ID for the settlement originating the funds being transfered.
A string in the format settlement_[0-9a-z].
An object describing the target project of the transfer.
Name
release_at
Type
string
Description
A date that describes when the funds should be automatically transfered.
Name
metadata
Type
object
Description
A free-form metadata object that you can use to store against the transfer.
A list of transfers to create.

Request

POST

/v1/transfers

curl -X POST https://rest.trustshare.io/v1/transfers \ 
  -H "Authorization: <private_key>" \ 
  -d @- << EOF
  {
    "transfers": [
      {
        "amount": 25000,
        "from": {
          "project_id": "project_Tk1B74J4qq"
        },
        "to": {
          "project_id": "project_hbo76KAZkG"
        },
        "metadata": {
          "foo": "can store my metadata"
        }
      }
    ]
  }
  EOF

Response

{
  "transfers": [
    {
      "id": "transfer_XkXoRYNDd2",
      "created_at": "2023-12-20T15:10:17.126Z",
      "updated_at": "2023-12-20T15:10:17.126Z",
      "status": "awaiting_funds",
      "amount": 25000,
      "from": {
        "project_id": "project_Tk1B74J4qq",
        "settlement_id": null
      },
      "to": {
        "project_id": "project_hbo76KAZkG",
        "settlement_id": null
      },
      "inbound_id": null,
      "outbound_id": "outbound_QITD6jr2KA",
      "release_at": null,
      "metadata": {
        "foo": "can store my metadata"
      }
    }
  ]
}