Transfer Participants

Understand how to create a transfer with participants

What is a participant?

Transfer participants describe the ultimate senders and receivers of funds in a transfer, ensuring that a partner's usage of the Cybrid Platform remains within all compliance requirements.

A participant is a bank, customer, or counterparty that is involved in a transfer as either a sender or as a receiver. Participants that are senders are considered source participants. Participants that are receivers are considered destination participants. In a transfer, there will be one or more source participants and one or more destination participants.

When do I have to specify participants?

Partners must specify participants for all transfers, except the inter_account transfer type. While the Cybrid Platform could infer participants automatically, compliance requires partners to explicitly describe the flow of funds to prevent accidental omissions.

How do I specify participants?

When creating a transfer, the source_participants and destination_participants fields must be used to supply the type and identifiers of the participants, as well as their corresponding amounts.

Both fields are arrays, supporting batch transfer scenarios where funds are dispersed to multiple parties. The sum of the source_participants amounts and the sum of the destination_participants amounts must each equal the total transfer amount.

When performing a withdrawal to a customer-owned external bank account, ensure that the participant is set to the corresponding customer (using the customer GUID), not the bank. Attempting to use a customer-owned external bank account with the participant set to the bank will result in an error.

Example: Remittance partner withdrawing funds from the Cybrid Platform

In this example, a remittance partner batch transfers funds to an external wallet they control before dispersing funds to external parties modelled as counterparties. The destination participants are all counterparties ultimately receiving the funds, while the source participants are a single entry for the partner's bank.

A partial POST /api/transfers example:

{
  ...
  "source_participants": [
    {
      "type": "bank",
      "amount": "<insert total amount>",
      "guid": "<insert bank_guid>"
    }
  ],
  "destination_participants": [
    {
      "type": "counterparty",
      "amount": "<insert first partial amount>",
      "guid": "<insert first counterparty_guid>"
    },
    {
      "type": "counterparty",
      "amount": "<insert second partial amount>",
      "guid": "<insert second counterparty_guid>"
    }
  ],
 ...
}

Example: On-ramp partner depositing funds into the Cybrid Platform

In this example, an on-ramp/off-ramp partner pulls funds from their customer's external bank account. Both source and destination participants reference the same customer GUID.

A partial POST /api/transfers example:

{
  ...
  "source_participants": [
    {
      "type": "customer",
      "amount": "<insert amount>",
      "guid": "<insert customer_guid>"
    }
  ],
  "destination_participants": [
    {
      "type": "customer",
      "amount": "<insert amount>",
      "guid": "<insert customer_guid>"
    }
  ],
  ...
}

Counterparties and account ownership

For book transfers to the partner account, counterparties must be attached. Counterparties are not required for on-chain (crypto) transfers.

⚠️

Funding transfer participant types

For funding transfers, both source_participants and destination_participants should typically be of type customer and reference the appropriate customer GUIDs. If you intend to send funds to a counterparty, you must create a credit-only external bank account for that counterparty and use it as the destination.

The ownership of fiat accounts must match the owner of the quote: if the quote is customer-owned (i.e., includes a customer_guid), the fiat account must belong to that customer. If the quote is bank-owned, the fiat account must belong to the bank. Omitting the customer_guid in a quote results in a bank-level quote, which cannot access customer-owned fiat accounts and may cause 'Account not found' errors.

Our counterparty documentation contains more technical guides.