SendPayments

## Send Payments API

The Send Payments API provides a flexible way to manage domestic and international payments. 


It's designed to be flexible, allowing a broad range of use cases. This document provides information on the endpoints offered by Send and how to interact with them. You can use these end points to create your own custom workflows or you can implement the workflows we have documented on the Send website.

API Reference and Guides

Overview & End to end flow

Authentication

Accounts

Wallets

Trades

Payments

Webhooks

Sandbox endpoints are only valid in our demo environment and can be used to simulate events you would not normally have control over.

Sandbox

Important points

Blank

User Guides

Send Partner API

Production

Sandbox environment

422 Error Message List

/accounts/{accountId}

/accounts/{accountId}/authorised-representatives

/accounts/{accountId}/recipients

/accounts/{accountId}/trades

/accounts/{accountId}/wallets

/accounts/corporate

/accounts/individual

Andorra

Argentina

Austria

Australia

/auth

Authenticating Webhooks

Available Currencies

Batch Trades

Belgium

Bermuda

Brazil

Brunei

Bulgaria

Canada

Chile

China

Collections & Pagination

Colombia

Country Payout Guides

Croatia

Cyprus

Czech Republic

Data Types

Denmark

Endpoints

Estonia

Example Routing Codes And Ibans

Fiji

Finland

France

Germany

Greece

Guatemala

Guernsey

Honduras

Hong Kong

Hungary

Iceland

Idempotent Requests

India

Indonesia

Ireland

Isle of Man

Israel

Italy

Japan

Jersey

Kenya

Latvia

Liechtenstein

Lithuania

Luxembourg

Macau

Malaysia

Malta

Mauritius

Mexico

Monaco

Netherlands

New Zealand

Nicaragua

Norway

Panama

Papua New Guinea

/payin-addresses

/payment-addresses/{paymentAddressId}

Payment Reasons

/payments/{paymentTransactionId}

/payments/payout

/payments/reason-codes

/payments/transfer

Peru

Philippines

Poland

Portugal

Qatar

/quotes

/quotes/{quoteId}

/rate-sheets

/rate-sheets/{rateSheetId}

/recipients

/recipients/{recipientId}

/recipients/{recipientId}/payment-addresses

Romania

Saint Kitts And Nevis

Samoa

San Marino

/sandbox/accounts/{accountId}

/sandbox/payins

/sandbox/recipients/{recipientId}

Saudi Arabia

Status Codes & Error Messages

Serbia

Singapore

Slovakia

Slovenia

South Africa

South Korea

Spain

Sweden

Switzerland

Taiwan

Thailand

Trinidad And Tobago

Turkey

United Arab Emirates

United Kingdom

Vanuatu

Vietnam

Zambia

/payments

Testing In The Sandbox

/trades/batch

/trades/batch/{batchId}

/trades/batch/{batchId}/entries

/trades/batch/{batchId}/submit

Trade Settlement and Cut-offs

/trades

/trades/{tradeTransactionId}

/wallets

/wallets/{walletId}

/wallets/{walletId}/payin-addresses

/wallets/{walletId}/payins

/wallets/{walletId}/payins/{payinId}

Webhook Delivery And Sequencing

Webhook Payloads

/webhooks

/webhooks/{webhookId}

We offer a range of `HTTP Endpoints` to create and manage **Accounts**, **Wallets**, **Trades**, **Payments**, **Webhooks** and other objects. 

`POST requests` are [Idempotent](doc:idempotent-requests) if the header parameter is used. These expire after 24 hours.

Generally, request bodies are JSON objects and response bodies are JSON objects that can contain single objects or collections.

When you create a new object, the response will include unique **identifiers** for the object and relevant nested objects. 

All `POST endpoints` have 1 or more associated `GET endpoints` to retrieve specific objects via their identifiers.

When an object is created, the response body will contain the data from the request body along with standard metadata which includes:

* `status`
* `createdAt`
* `updatedAt`

Endpoints that can return multiple objects (e.g. an array of Accounts), implement [pagination](doc:collections-pagination) and limited filtering.

You can subscribe to a range of events using **Webhooks**. After the `status` value of an object is changed, or a transaction created,\
an event is raised and will be sent the URLs you have specified. See [Webhooks](doc:webhooks-1) page for a list of all possible events\
(some may not be applicable to your agreement).

We also provide a sandbox endpoint for our non-production environments which you can use to simulate production-like scenarios such as creating a PayIn.

<LeaveUsADiscussionBoardPost />

**Idempotency** means repeating an action has the same effect as the first instance of the action. i.e. it's safe to perform the action more than once as it's not going to create duplicates or cause confusing or ambiguous records.

When interacting with an HTTP API it is possible that a request is successfully processed and/or the datastore updated, but either an error response or no response is received by the requester due to a connectivity error. In this case the requester may retry the request and accidentally perform the action more than once e.g. creating duplicate records.

In order to prevent this scenario, we recommend using the optional **Idempotency** header parameter on POST requests. (The **Idempotency** header parameter is unnecessary for GET and DELETE requests as they are intrinsically idempotent.)

The **Idempotency** header parameter allows the **Send Payments API** to determine if the request has previously been executed and if so, avoid executing it again. If the **Idempotency** parameter is included in the header, then the request MAY be considered idempotent otherwise it MUST NOT be considered idempotent.

In practice, if the **Idempotency** header parameter is provided, then the **Send Payments API** will check an internal cache for a request with the same parameters and body. If one exists, then the cached response is returned (regardless of whether the response was an error or not). If a cached request/response is not found, the endpoint will execute the request, send the response and add the record to the cache.

Records are removed from the cache after 24 hours. If you reuse a value for the **Idempotency** header parameter after 24 hours elapsed since its first use, it will be treated as a new request. Requests that do not include the **Idempotency** header parameter are not added to the cache and are not idempotent.

You can use any value for the **Idempotency** header parameter as long as it conforms to the following format:

String up to 36-characters in length using any of:

* upper-case letters
* lower-case letters
* digits from 0 to 9
* characters \_+=/
* Conforms to regex: ^[a-zA-Z 0-9-\_+=/][a-zA-Z 0-9-_+=/]\*$

You may choose to generate a unique value for the **Idempotency** header parameter and store this for use with subsequent requests or you may choose to supply your system’s unique identifier for an equivalent object (e.g. an `tradingAccountId `or `paymentTransactionId`).

<LeaveUsADiscussionBoardPost />

In this section we describe the _data types and formats_ generally used by the **Send Payments API**. 

## JSON data types

Generally, when the **Send Payments API** requires a `body` parameter within a request or when it returns a `body` parameter in a response or [Webhook](../webhooks) outbound request, then the body is a `JSON` object.

For requests (to Send, and from Send Webhooks to your Endpoints), when the Content-Type parameter is set to application/json and for responses to GET requests, the body parameter conforms to ECMA standard JSON which is limited to the JSON data types: 

- string
- number
- JSON object
- array
- true
- false

## Underlying data types

In addition to the `JSON` data types, we provide the underlying data types that are contained within the `JSON` data type, and formats for each `JSON` object. In some cases, these aren’t data types in the strict sense but are descriptions of common formats. 
e.g. we describe our unique identifiers as `UUID`. 

Where we have included a defined data type, e.g. String, then we have included the language (usually JavaScript) so you know the correct definition. 

Where the specific key value has a length or format requirement that is different from the basic data types below, then we will provide this in the endpoint description.

Although not strictly enforced, the table below is a guide to the minimum and maximum sizes and formats that the data within the body parameter of a request or response is likely to take.

e.g. The JSON key named `birthDate` is a string, but it has a generic underlying data type representing a date and is in the format “YYYY-MM-DD”.

"birthDate" : "1984-08-04"

| JSON data type | Underlying data type | Min size | Max size | Format | Example |
| -------------- | ------------------------------------------- | ------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| string | String (JavaScript) | 0 characters | 256 characters | Key value specific | `"firstName" : "John" ` |
| number | Integer64 (JavaScript) | | 64 bit integer | Money is expressed in integers representing the lowest denomination of the currency. | 11 = $0.11 (11 cents), 111 = $1.11 (111 cents) |
| number | Number64 (JavaScript) | | 64 bit double precision floating point | Key value specific | `"rate" : 11.11111` |
| true or false | Boolean | | | Either the value “true” or the value “false” without quotes | `"termsAndConditionsAccepted" : true ` |
| string | Date (String) (JavaScript) | 10 characters | 10 characters | [ISO - ISO 8601 — Date and time format](https://www.iso.org/iso-8601-date-and-time-format.html) YYYY-MM-DD | `"birthDate" : "2017-07-21"` |
| string | Date-Time (String) (JavaScript) | 24 characters | 24 characters | [ISO - ISO 8601 — Date and time format](https://www.iso.org/iso-8601-date-and-time-format.html) YYYY-MM-DDThh:mm:ss.sssZ Note the “.” separator indicating a fractional part for seconds i.e. milliseconds. We usually express Date-Times in UTC time, indicated by the “Z” character on the end of the format string. | `"createdAt" : 2017-07-21T17:32:28.878Z` |
| string | UUID (String) (JavaScript) | 36 characters | 36 characters | The UUID format that we use is 36 characters in length and made up of 5 groups of hexadecimals with the following lengths: 8-4-4-4-12 [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122) | `5e505642-9024-474d-9434-e5a44f505cc` |
| string | Enum (String) (JavaScript) | 1 character | 50 characters | | Enum name: `“EnumIdentityType”` Enum allowed values: `“drivers_license”` `“passport”` `"identityType" : "drivers_license"` |
| string | Email (String) (JavaScript) | 3 characters | 254 characters | See RFC 3696 with errata [rfc3696](https://www.rfc-editor.org/rfc/inline-errata/rfc3696.html) | a@b |
| string | Country codes (String) (JavaScript) | 2 characters | 2 characters | [ISO - ISO 3166 — Country Codes](https://www.iso.org/iso-3166-country-codes.html) | AU = Australia |
| string | Currency codes (String) (JavaScript) | 3 characters | 3 characters | [ISO - ISO 4217 — Currency codes](https://www.iso.org/iso-4217-currency-codes.html) | AUD = Australian Dollar |
| string | Country calling codes (String) (JavaScript) | 2 characters | 5 characters | “+” character followed by up to 4 digits +xxxx [LIST OF ITU-T RECOMMENDATION E.164 ASSIGNED COUNTRY CODES](https://www.itu.int/dms_pub/itu-t/opb/sp/T-SP-E.164D-11-2011-PDF-E.pdf) | \+61 = Australia +64 = New Zealand |
| string | Phone numbers (String) (JavaScript) | 3 characters | 15 characters | Up to 15 digits [E.164 : The international public telecommunication numbering plan Sec 6.1](https://www.itu.int/rec/T-REC-E.164-201011-I) | 0295643823 |

## Amount key value pairs

Denoting amounts in international currencies can be tricky because many have varying denominations f.e cents and dollars, or pennies and pounds. To ensure consistency throughout the API, amounts are always defined by a currencies lowest value denomination as a 64 bit integer.

Floating point data types are not used for amounts as some mathematical operations on floats can result in a loss of accuracy. 

Note: floating point numbers are used for some key values such as rates, but not for currency amounts. 
For dollar currencies (like $AUD), $110 and $0.15 would be represented as follows:

```
"amount": 11000,
"amount": 15
```

Some currencies (Like ¥JPY) have only one denomination. ¥110 would be represented as follows:

```
"amount": 110
```

## Enumerations (Enums)

Some JSON objects must take one of a specific set of values exactly. We will tell you when a key value is an Enum so you'll know which values must be used. e.g. The JSON object named “identityType” is a JSON string, but it has an underlying data type which must be a value from a specific set of values i.e. it is an enumerated type or Enum.

Enum name: `“EnumIdentityType”`

Enum allowed values: `“drivers_license”`, `“passport”`

You might use it like this:

`{"identityType" : "drivers_license"}` 
or 
`{"identityType" : "passport"}`

but any other value would cause and error (not the space character) 
`{"identityType" : "drivers license"}`

## Lists

In the **Send Payments API** documentation, **Lists** are reference data, similar to Enums. When we talk about **Lists** we mean it in the way you would use it in everyday English, we do not mean an ordered list of values as in the computer science definition. Some JSON objects must take one of a specific list of values exactly. We will tell you when a key value must be from a **List**.

**Send Payments API Lists** require key values to come from a specified list of values, however they differ from _Enums_ in that they:

- Are more likely to change over time.
 - new values added, existing values removed.
 - values activated or deactivated temporarily.
 - e.g. Send Payments does not offer payments in certain currencies, however, Send Payments may at its discretion, enable or disable a currency in the future.

- May be limited by agreement with a customer. The details of your agreement with Send Payments may mean that certain options are unavailable or are irrelevant to you.
 - e.g. You may require access to certain currencies but not others.

- Changes do not necessarily require a new version of the API.

Agreement level lists are shared with your organization as part of your agreement with Send Payments.

<LeaveUsADiscussionBoardPost/>

Some endpoints within the **Send Payments API** return collections which may contain large numbers of objects.\
We provide the following optional *query parameters* to allow you to limit the number of objects returned per request to a size that is manageable for you.

* `page`
* `limit`
* `sortBy`
* `sortOrder`

In the **Send Payments Ecosystem** all *JSON* objects that can be part of a collection have the following key value pairs:

* `createdAt` (YYYY-MM-DDThh:mm:ss.sssZ) The UTC date time that the object was created.
* `updatedAt` (YYYY-MM-DDThh:mm:ss.sssZ) - The UTC date time that the object was last updated.

The default order for all collections is first by `createdAt` ascending then by `updatedAt` ascending.

The maximum number of objects returned per GET response is currently limited to 1000\
regardless of whether pagination parameters have been provided in the URL.\
When interacting with the **Send Payments API** do not assume this value will be the same between requests as we may\
change default value at our discretion without notice and without changing the version of the API.\
If you require access to more objects than is allowed by the default then use the pagination parameters.

All Endpoints that apoint to a collection return a response that contains the following:

* An array containing zero or more objects from the collection up to the maximum - this is the requested data from the collection.
* An object representing metadata about the response including pagination details.

| Body parameter key (JSON) | Underlying data type | Description |
| ------------------------- | -------------------- | ----------------------------------------------------------------------- |
| items\[] | Array[Object] | An array of objects from the collection |
| meta | Object | Object containing metadata details such as record counts and pagination |
| meta/itemCount | int64 | The amount of items on this specific page |
| meta/totalItems | int64 | The total amount of items |
| meta/itemsPerPage | int64 | The amount of items that were requested per page |
| meta/totalPages | int64 | The total amount of pages in this paginator |
| meta/currentPage | int64 | The current page this paginator "points" to |

<details>
<summary>Response example for GET/payments?limit=3&page=1</summary>

```json
{
 "data" : [
{
 "objectName" : "myObjectName1",
 "objectId" : "xxxx_1111111",
 "createdAt" : "2023-09-01T08:00:22Z",
 "updatedAt" : "2023-09-01T08:10:22Z"
 },
 {
 "objectName" : "myObjectName2",
 "objectId" : "xxxx_2222222",
 "createdAt" : "2023-09-01T08:00:22Z",
 "updatedAt" : "2023-09-01T08:00:22Z"
 },
 {
 "objectName" : "myObjectName3",
 "objectId" : "xxxx_3333333",
 "createdAt" : "2023-09-01T08:00:19Z",
 "updatedAt" : "2023-09-01T08:00:19Z"
 }
 ],
 "meta" : 
 {
 "itemCount": 3, 
 "totalItems": 30, 
 "itemsPerPage": 3, 
 "totalPages": 10, 
 "currentPage": 1
 }
}
```

</details>

The `totalItems` key shows that there are 30 objects in the collection and the `itemCount` shows that within this request there are 3 objects.

<LeaveUsADiscussionBoardPost />

Send Legacy API

Sections

Important points

On this page