Payments

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.

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 Customer 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:

• accountId;
• 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.

 
{
  "accountId": "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": "kad@sendpayments.com",
  "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

 
{
  "item": {
    "accountId": "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": "kad@sendpayments.com",
    "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

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

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.

 
{
 "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.

 
{
  "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.

 
{
  "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.

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

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.

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.

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 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

 
{
  "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.

 
{
  "item": {
    "paymentTransactionId": "string",
    "paymentReason": "string",
    "paymentDate": "2024-

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 Account

To request all the Recipients for the specific Account you can send a signed GET accounts/{accountId}/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 Account.

Note that standard pagination rules are applied for the response.

Fetching all Payment Addresses for the Recipient

To request all the Payment Addresses for the specific Recipient you can send a signed GET recipients/[recipientId]/payment-addresses 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 recipientId in the API key, a SUCCESS response will return the information for all the Payment Addresses for a specific Recipient.

Note that standard pagination rules are applied for the response.

Fetching a previously created Recipient

To request the information for a given Recipient you can send a signed GET /recipients/[recipientId] request.

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.

Given a valid recipientId in the URL, a SUCCESS response will return the information for the given Recipient

Note that standard pagination rules are applied for the response.

Fetching a previously created Payment Address

To request the information for a given Payment Address you can send a signed GET /payment-addresses/{paymentAddressId} request.

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.

Given a valid paymentAddressId in the URL, a SUCCESS response will return the information for the given Payment Address

Note that standard pagination rules are applied for the response.

Fetching all the Payments for the enterprise account

To request all the Payments for the specific enterprise account you can send a signed GET /payments 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 payments for a specific Enterprise Account.

Note that standard pagination rules are applied for the response.

Fetching a specific Payment Transaction

To request the information about a specific Payment Transaction you can send a signed GET /payments/{paymentTransactionId} 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 paymentTransactionId in the URL, a SUCCESS response will return the information for a specific Payment Transaction.

Note that standard pagination rules are applied for the response.

Fetching all Payments within a specific Account

To request the information about all the Payments made for the Account you can send a signed GET /accounts/{accountId}/payments 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 URL, a SUCCESS response will return all the Payments made for the Account.

Note that standard pagination rules are applied for the response