Description

Payments are one of the main features of the platform. They can be used to send money to a Recipient and Payment Address outside the Send Ecosystem (further - Payouts), or to move money between Wallets within the Send Ecosystem (further - Transfers).

Creating a Recipient with a Payment Address is mandatory if you want to make a Payout. A Recipient refers to the individual or corporate you want to pay. The Payment Address is the banking details the Recipient holds. A Recipient can hold multiple Payment Addresses.

🚧
A Recipient & Payment Address must be Active before creating a Payout

Recipients

How to create a Recipient

To create a Recipient you need to send a POST /recipients request including the accessToken you’ve received
during the Authentication process in the headers.

Each Recipient is linked to the Trading Account specified in the create Recipient request.

Payment Address must be added within the request to create a Recipient. If the Recipient has several Payment Addresses they can be added in a separate request later on.

Depending on whether your Recipient is a corporate or an individual, the request to create a Recipient will require different sets of data.

This request must contain the following:

tradingAccountId;
recipientType;
firstName, lastName and physicalAddress Object (for Individual Recipients only)
corporateName, corporateRegistrationNumber, corporateCountryofRegistration and physicalAddress Object (for corporate Recipients only)
paymentAddresses Object

The required fields will differ based on where the payments are being sent so please refer to Country Payout Guides page.

While in Processing status, Recipient undergo a Compliance Check (if any action is required at this point, Send will reach out via established channels to rectify any issues/gather necessary documentation).

At this point, if Compliance fails the Recipient it will go into a Rejected status. Otherwise the Recipient will go into Active status.

To receive updates on the Recipient status changes please refer to Webhooks.

Request example for POST /recipients

{
  "tradingAccountId": "zyxw3214-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "clientReferenceName": "string",
  "firstName": "Kim",
  "lastName": "Alex",
  "middleName": "Doe",
  "recipientType": "individual",
  "countryOfResidence": "AU",
  "physicalAddress": {
    "city": "Christchurch",
    "country": "NZ",
    "postcode": 8011,
    "state": "string",
    "addressLine1": "1 Short Street",
    "addressLine2": "string",
    "streetName": "string",
    "streetNumber": "string",
    "streetType": "string",
    "unitNumber": "string"
  },
  "phoneCountryCode": "61",
  "phoneNumber": 78945678,
  "email": "[email protected]",
  "dateOfBirth": "2001-04-07T00:00:00.000Z",
  "taxIdentifier": "string",
  "paymentAddresses": [
    {
    "payoutType": "swift",
    "routingCode": "12345789",
    "accountReference": "49995300",
    "accountName": "My Account Name",
    "externalReference": "ref-12345789",
    "currency": "AUD",
    "clientAddressName": "My payment address",
    "bankCountry": "AU",
    "accountType": "checking"
    }
  ]
}

In response to your request you will receive either a SUCCESS 201 response or one of the error responses (400, 401, 500). See Status Codes & Error Messages.

Within the successful response you will receive all the data you’ve provided with the following data included:

recipientId which can be used to refer to the Recipient
status
createdAt and updatedAt dates and time.
paymentAddress Object details

Response example for POST /recipients

{
  "item": {
    "tradingAccountId": "zyxw3214-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
    "clientReferenceName": "string",
    "firstName": "Kim",
    "lastName": "Alex",
    "middleName": "Doe",
    "recipientType": "individual",
    "countryOfResidence": "AU",
    "physicalAddress": {
      "city": "Christchurch",
      "country": "NZ",
      "postcode": 8011,
      "state": "string",
      "addressLine1": "1 Short Street",
      "addressLine2": "string",
      "streetName": "string",
      "streetNumber": "string",
      "streetType": "string",
      "unitNumber": "string"
    },
    "phoneCountryCode": "61",
    "phoneNumber": 78945678,
    "email": "[email protected]",
    "dateOfBirth": "2001-04-07T00:00:00.000Z",
    "taxIdentifier": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "status": "submitted",
    "recipientId": "1k2l3m4-9i0j-7g8h-9i0j-1k2l3m4n5o62",
    "paymentAddresses": [
      {
        "paymentAddressId": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o61",
        "payoutType": "swift",
        "routingCode": "12345789",
        "accountReference": "49995300",
        "accountName": "My Account Name",
        "externalReference": "ref-12345789",
        "currency": "AUD",
        "clientAddressName": "My payment address",
        "bankCountry": "AU",
        "accountType": "checking"
        "createdAt": "2019-08-24T14:15:22Z",
        "updatedAt": "2019-08-24T14:15:22Z",
        "status": "pending"
      }
    ]
  }
}

Recipient & Payment Address Status Flow

📘
If you wish to make a Recipient or Payment Address Inactive, you will need to contact Send through agreed channels

SWIFT vs Local Payouts

You will need to stipulate the payoutType in the Payment Address. This can either be Local or SWIFT. In general Send will work with any Client to figure out the best Payment rails for their use case but please keep the following in mind:

SWIFT network is higher cost than Local but is considered a better rail for high priority and high value payments.
SWIFT network may also suffer from intermediary bank fees which can result in funds not arriving whole (f.e. a bank in the middle takes out $10 as a processioning fee)
Local rails have different processing timelines based on the country but usually take 1-2 days.
SWIFT usually arrives within a few hours (especially in Major currencies)

📘
NZD Local Payouts
NZD Local Payouts can only be made when a Trade and Payout are linked in the same request via POST/trades/spot.
Single currency NZD Payouts via the POST/payments/payout must be sent via SWIFT.

How to add a Payment Address to an existing Recipient

If you need to add more Payment Addresses for the Recipient you can add it as a separate request.

To add a Payment Address for an existing Recipient you need to send a signed POST /recipients/{recipientId}/paymentAddresses request.

This request must contain the following:

payoutType - Type of payment to be made. Please ensure you cross reference which routing details you are supplying with the payoutType to avoid any Payment failures.
routingCode - Routing code of the recipients bank, usually a local clearing code (ie BSB) or a SWIFT code.
accountReference - Specific account number for the Recipient's bank address. Usually a local account number or an IBAN.
currency - Currency of the Recipient's account.
bankCountry - Where the recipient's bank address is located.

Request example for POST /recipients/{recipientId}/payment-addresses

{
 "payoutType": "swift",
 "routingCode": "12345789",
 "accountReference": "49995300",
 "accountName": "My Account Name",
 "externalReference": "ref-12345789",
 "currency": "AUD",
 "clientAddressName": "My payment address",
 "bankCountry": "AU",
 "accountType": "checking"
}

In response to your request you can receive either a SUCCESS 201 response or one of the error responses (400, 401, 500). See Status Codes & Error Messages.

Within the successful response you will receive all the data you’ve provided with the following data included:

paymentAddresstId which can be used to refer to the Recipient
status
createdAt, updatedAt dates and time.

Response example for POST /recipients/{recipientId}/payment-addresses

{
  "item": {
    "paymentAddressId": "string",
    "payoutType": "swift",
    "routingCode": "12345789",
    "accountReference": "49995300",
    "accountName": "My Account Name",
    "externalReference": "ref-12345789",
    "currency": "AUD",
    "clientAddressName": "My payment address",
    "bankCountry": "AU",
    "accountType": "checking",
    "createdAt": "2024-08-09T05:58:17.918Z",
    "updatedAt": "2024-08-09T05:58:17.918Z",
    "status": "submitted"
  }
}

While in Processing status, Payment Address undergo a Compliance Check (if any action is required at this point, Send will reach out via established channels to rectify any issues/gather necessary documentation).

At this point, if Compliance fails the Payment Address it will go into a Rejected status. Otherwise the Payment Address will go into Active status.

Payouts

How to make a Payout

To make a Payout externally to an individual or corporate, you must first create a Recipient with a valid Payment Address. Both Recipient and Payment Address must have an Active status.

After that you need to send a POST /payments/payout request including the accessToken you’ve received during the Authentication process in the headers.

Within the request you must specify the following:

fromWalletId
recipientId and paymentAddressId (valid and active)
Payment currency and amount
Please note that fromWallet should have the same currency as the currency provided in the request.
Any currencies that require conversion should come via the Trade endpoint.
Available currencies list depends on the contract agreement between you and Send and is based on whitelisting.
paymentReason and reference
The paymentReason is required to ensure the payout is processed successfully. The reason that can be selected will vary based on the country the payout is sent to.
The reference is what the Recipient will see on the Transaction when they receive it.
The length of the reference may vary depending on the rails of the Payment.

📘
Certain countries have specific payment reasons that must be provided. Please refer to the Payment Reasons for further information.

Request example for POST /payments/payout

{
  "paymentReason": "buying_a_vehicle",
  "reference": "string",
  "currency": "AUD",
  "amount": 10000,
  "fromWalletId": "4321dcba-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "recipientId": "4567xyzw-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "paymentAddressId": "1234abcd-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "externalReference": "string"
}

After the creation of the Payout request it undergoes a number of validation checks before creating the Payment Transaction and sending back a response.

In response to your request you will receive either a SUCCESS 201 response or one of the error responses (400, 401, 500). See Status Codes & Error Messages.

Within the successful response you will receive all the data you’ve provided with the paymentTransactionId, paymentType (for payouts it will always be “payout”), payoutType (either “swift” or “local”), status of the Transaction, createdAt and updatedAt dates and time.

To receive updates on the Payment Transaction status changes please refer to Webhooks.

Response example for POST /payments/payout

{
  "item": {
    "paymentTransactionId": "string",
    "paymentReason": "string",
    "reference": "string",
    "paymentType": "payout",
    "currency": "AUD",
    "amount": 0,
    "fromWalletId": "string",
    "recipientId": "string",
    "paymentAddressId": "string",
    "rejectReason": "string",
    "status": "submitted",
    "createdAt": "2024-08-09T05:58:17.918Z",
    "updatedAt": "2024-08-09T05:58:17.918Z",
    "paymentDate": "2024-08-09",
    "externalReference": "string",
    "payoutType": "swift"
  }
}

🚧
If a Payout has been returned
If a Payout to a particular Payment Address has returned then it is recommended to create another Payment Address for that Recipient as any other subsequent Payments will probably return as well.

How do Payouts work

Before a Payout is created it undergoes a round of checks to make sure everything is set correctly and no data is missing. These checks include:

Required data is provided;
Recipient and Payment Address are valid and active;
currency of Payout matches the fromWalletID;
currency is available for payments;
paymentReason has been provided.

Provided these validations pass, the status of the Payout will be set to “Processing” and a response with the paymentTransactionID will be sent back to you.

While in Processing status, Payouts undergo a Compliance Check (if any action is required at this point, Send will reach out via established channels to rectify any issues/gather necessary documentation).

At this point, if Compliance fails the Payout it will go into a Rejected status.

If a Payout was made via POST/trade, it will move to Pending Trade Settlement status when it has passed Compliance and stay there until the linked Trade is settled.
If however the Payout is booked via POST/payments/payout it will stay in Awaiting Funds status until the Wallet has been funded.

Once either of these occur, the Payout will move to Pending Release for the final checks before sending to the Recipient and moving the status to Released.

If the linked Trade fails/is rejected/is cancelled before the Payout is released it will move to Rejected status.

If a Payout is rejected by the bank for a particular reason Send will refund the Wallet and set the status of the the Payout to Returned. If that happens you will be notified via the Webhooks so you will know the exact reason of the failure.

If you wish to cancel a Payout that has been created, you will need to contact Send via the agreed channels.

🚧
Send will not retry failed Payouts automatically
In case if your Payment failed you will have to rebook it again.

Payout Status Flow

The Payout status flow differs slightly depending on if it is a single currency Payout via the POST /payments/payout or a Payout with a linked trade via POST /trade. If it's a single currency Payout it will be in Awaiting Funds until it has been funded. For a Payout with a linked trade, it will be in Pending Trade Settlement until the Trade hits the settlement day and has also been funded.

📘
Trade settlementDate vs Payment paymentReleaseDate
When booking a linked trade and payment, usually the settlementDate and paymentReleaseDate will be the same. However depending on when the trade is specifically funded and the time taken to process the Payout, the paymentReleaseDate may change. This is usually when booking trades into exotics where, due to liquidity restrictions, the payment may only be able to be released up to 2 days after funding of the trade. Another example is if a Trade is booked right before a cut-off, in this instance the Trade may settle, however the payment could miss its cut-off and be sent the following day.

Transfers

How to make a Transfer

To make a Transfer (to send funds to another Send Wallet) you need to make sure that a toWallet exists prior to making the Transfer. Transfers can be done between the Wallets from different Trading Accounts.

After that you need to send a POST /payments/transfer request including the accessToken you’ve received
during the Authentication process in the headers.

Within the request you must specify the following:

fromWalletId
toWalletId
currency and amount
paymentReason and reference

🚧
Currencies must match
Please, make sure that both toWallet and fromWallet have the same currency and it should match the currency provided in the request. If the currencies differ, the Trades endpoint should be called.

Request example for POST /payments/transfer

{
  "paymentReason": "buying_a_vehicle",
  "reference": "My reference",
  "currency": "AUD",
  "amount": 50000,
  "fromWalletId": "4321dcba-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "toWalletId": "1234abcd-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
   "externalReference": "string"
}

After the creation of the Transfer request it undergoes a number of validation checks before creating Payment Transaction and sending back a response.

In response to your request you will receive either a SUCCESS 201 response or one of the error responses (400, 401, 500). See Status Codes & Error Messages.

Within the successful response you will receive all the data you’ve provided with the paymentTransactionId, paymentType (for transfers it will always be “transfer”), status of the Transaction, createdAt and updatedAt dates and time.

PaymentTransactionId can be used to refer to that Payment Transaction.

To receive updates on the Payment Transaction status changes please refer to Webhooks.

Response example for POST /payments/transfer

{
  "item": {
    "paymentTransactionId": "string",
    "paymentReason": "string",
    "paymentDate": "2024-08-09",
    "reference": "My reference",
    "paymentType": "payout",
    "currency": "AUD",
    "amount": 50000,
    "fromWalletId": "string",
    "toWalletId": "string",
    "status": "submitted",
    "createdAt": "2024-08-09T05:58:17.918Z",
    "updatedAt": "2024-08-09T05:58:17.918Z",
    "externalReference": "string"
  }
}

Most transfers will process instantaneously.

How do Transfers work

Before a Transfer is created it undergoes a round of checks to make sure everything is set correctly and no data is missing.

After the system has checked that the following conditions have been met:

needed data is provided;
toWallet is valid and active (for Transfers)
currency match the Wallets

The status of the Transer will be set to “Processing” and response with the paymentTransactionID will be sent back to you.

While in Processing status, Transfers undergo a Compliance Check (if any action is required at this point, Send will reach out via established channels to rectify any issues/gather necessary documentation).

At this point, if Compliance fails the Transfer it will go into a Rejected status.

Once Compliance pass the Transfer it will go into Awaiting Funds status until the funds have been received. Once received, the Transfer will go to Settled status

Transfer Status Flow

Fetching Information

Fetching all Recipients for the Trading Account

To request all the Recipients for the specific Trading Account you can send a signed GET accounts/{tradingaccountId}/recipients request.

In response to your request you will receive either a SUCCESS 200 response or one of the error responses (400, 401, 500). See Status Codes & Error Messages.

Given a valid accountId in the API key, a SUCCESS response will return the information for all the Recipients for a specific Trading Account.