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

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}

To ensure the security and integrity of webhooks sent by the Send platform, each request includes specific headers that can be used to verify its authenticity.

## X-Send-Signature

This header contains a signature generated by signing the timestamp (`X-Send-Request-Timestamp` header) and the message body using an asymmetric SHA256 private key. This signature can be used to ensure that the webhook originated from the Send platform and has not been altered.

**Verifying the Signature**\
To verify the signature, follow these steps:

1. Stringify the webhook body.
2. Prefix the stringified body with the value from the `X-Send-Request-Timestamp` header.
3. Use the provided public key to verify the signature.

An example of this implemented in Node.js is as follows:

```
const fs = require('fs');
const crypto = require('crypto');

const calculateStringToVerify = (webhookBody, timestampHeader) => {
  const bodyString = JSON.stringify(webhookBody);
  return `${timestampHeader}${bodyString}`;
}

const verifySignature = async (webhookBody, timestampHeader, signatureHeader) => {
  // Create the string to verify
  const stringToVerify = calculateStringToVerify(webhookBody, timestampHeader);

  // Retrieve the public key
  const publicKey = fs.readFileSync('./public-key.pem', 'utf8');

  // Set up the verifier
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(stringToVerify);
  verifier.end();

  // Verify the signature
  const isVerified = verifier.verify(publicKey, signatureHeader, 'base64');
  return isVerified;
}
```

If you intend to implement signature verification for incoming webhooks, please contact the Send team to obtain the current public key.

## X-Send-Request-Timestamp

This header contains an ISO 8601 timestamp (UTC), indicating when the webhook was sent. To mitigate the risk of replay attacks, we recommend rejecting any webhook messages older than a threshold of your choosing.

This timestamp is also used in the signature calculation process described above.

Due to the distributed nature of Send’s platform, we cannot guarantee that every intermediate status transition for an object will be delivered via webhook. While we aim to provide comprehensive status updates, there are specific considerations to keep in mind:

* **First and Last Events**: Send ensures that the first and last status change events for each object are always delivered reliably.
* **Intermediate States**: In cases where objects transition through processing states rapidly, intermediate status events may occasionally be skipped. This is an expected behaviour to ensure efficiency and system performance.
* **Even Sequencing**: Please be aware that webhooks can sometimes arrive out of order. Take note of the `createdAt` timestamp in webhooks to ensure you process them in the correct order.

### Recommendations for Developers

To handle potential gaps in intermediate status events:

1. Design your system to rely on the guaranteed delivery of the first and last status events for critical workflows.
2. Implement mechanisms to query the latest status of an object using the appropriate API endpoints if intermediate states are essential for your application.
3. Use webhooks in conjunction with periodic reconciliation processes to ensure data consistency.

### Customer Account Webhook

```json
{
  "id": "2bde2e5a-7606-49c2-b28e-253792258e34",
  "customerAccountId": "2bde2e5a-7606-49c2-b28e-253792258e34",
  "status": "active",
  "externalReference": "2bde2e5a-7606-49c2-b28e-253792258e34",
  "updatedAt": "2024-02-09T13:30:00Z"
}
```

| Attribute         | Type                 | Description                                                                                          | Rules    |
| :---------------- | :------------------- | :--------------------------------------------------------------------------------------------------- | :------- |
| id                | string \[uuid]       | Unique identifier of the webhook                                                                     | Required |
| customerAccountId | string \[uuid]       | Unique identifier of the customer account                                                            | Required |
| status            | enum                 | Status of the Customer Account                                                                       | Required |
| externalReference | string               | An optional value that can be passed in to later reference a related resource in the partner system. | Optional |
| updatedAt         | string \[stimestamp] | The timestamp with timezone for date when Payment Address was updated                                | Required |

Status enum:

```json
CustomerAccountStatus {
  submitted,
  pending,
  active,
  inactive,
  rejected
}
```

***

### Wallet Webhook

```json
{
  "id": "18b455af-9f60-43de-8f4b-b94f8e1b6e8b",
  "walletId": "18b455af-9f60-43de-8f4b-b94f8e1b6e8b",
  "tradingAccountId": "bfdb26af-655a-4ee2-9328-a480f4c204d7",
  "currency": "NZD",
  "status": "active",
  "availableBalance": 0,
  "cashBalance": 0,
  "committedBalance": 0,
  "updatedAt": "2024-02-14T00:01:08Z"
}
```

| Attribute        | Type                 | Description                                                   |
| :--------------- | :------------------- | :------------------------------------------------------------ |
| id               | string \[uuid]       | Unique identifier of the webhook                              |
| walletId         | string \[uuid]       | Unique identifier of the wallet object                        |
| tradingAccountId | string \[uuid]       | Unique identifier of attached trading account                 |
| currency         | string               | 3-letter Currency in what currency this wallet is denominated |
| status           | enum                 | Status of the wallet                                          |
| availableBalance | integer              | wallet available balance                                      |
| cashBalance      | integer              | wallet cash balance                                           |
| committedBalance | integer              | wallet receivable balance                                     |
| updatedAt        | string \[stimestamp] | The timestamp with timezone for when the record was updated.  |

Status enum:

```json
WalletStatus {
  pending,
  active,
  inactive
}
```

***

### Pay-In Address Webhook

```json
{
  "id": "18b455af-9f60-43de-8f4b-b94f8e1b6e8b",
  "pay-inAddressId": "18b455af-9f60-43de-8f4b-b94f8e1b6e8b",
  "status": "active",
  "updatedAt": "2024-02-14T00:01:08Z"
}
```

| Attribute       | Type                            | Description                                                           | Rules    |
| :-------------- | :------------------------------ | :-------------------------------------------------------------------- | :------- |
| id              | string \[uuid]                  | Unique identifier of the webhook                                      | Required |
| pay-inAddressId | string \[uuid]                  | Unique identifier of the Pay-In address object                        | Required |
| status          | enum: active, pending, inactive | Status of the pay-in address                                          | Required |
| updatedAt       | string \[stimestamp]            | The timestamp with timezone for date when Payment Address was updated | Required |

Status enum:

```json
Pay-InAddressStatus {
  pending,
  active,
  inactive
}
```

***

### Pay-In Transaction Webhook

```json
{
  "id": "9757e4bc-f9ba-49f0-beb8-1557f308b0ee",
  "pay-inId": "9757e4bc-f9ba-49f0-beb8-1557f308b0ee",
  "tradingAccountId": "bfdb26af-655a-4ee2-9328-a480f4c204d7",
  "pay-inAddressId": "987654321",
  "walletId": "9757e4bc-f9ba-49f0-beb8-1557f308b0ee",
  "amount": 1000,
  "currency": "USD",
  "status": "pending",
  "source": "BSB=944-600,ACC NO=016043596",
  "remitterDetails": "M J & L J L HATT",
  "reference": "2697D",
  "type": "local_bank_transfer",
  "updatedAt": "2024-03-21T10:05:00Z",
}
```

| Attribute        | Type                 | Description                                                                        | Rules    |
| :--------------- | :------------------- | :--------------------------------------------------------------------------------- | :------- |
| id               | string \[uuid]       | Unique identifier of the webhook                                                   | Required |
| pay-inId         | string \[uuid]       | Unique identifier of the Pay-In transaction                                        | Required |
| tradingAccountId | string \[uuid]       | Unique identifier of attached trading account                                      | Required |
| pay-inAddressId  | string \[uuid]       | Unique identifier of the Pay-In address object                                     | Required |
| walletId         | string \[uuid]       | Unique identifier of the wallet object                                             | Required |
| amount           | integer              | Transaction Amount                                                                 | Required |
| currency         | string               | 3-letter Currency of the pay-In                                                    | Required |
| status           | enum                 | Pay-in transaction status                                                          | Required |
| source           | string               | The source response includes information about 'where' the Pay-In originated from. | Required |
| remitterDetails  | string               | The remitter response includes information about 'who' the Pay-In originated from. | Required |
| reference        | string               | This is reference that the sender of the Pay-In would put on their bank transfer.  | Optional |
| type             | enum                 | Pay-In transaction type                                                            | Required |
| updatedAt        | string \[stimestamp] | The timestamp with timezone for when the record was updated.                       | Required |

Status enum:

```json
Pay-Intransaction {
  new,
  pending,
  credited,
  rejected
}
```

***

### Trade Webhook

```json
{
  "id": "9757e4bc-f9ba-49f0-beb8-1557f308b0ee",
  "paymentAddressId": "uuid",
  "tradingAccountId": "uuid",
  "status": "pending",
  "externalReference": "2bde2e5a-7606-49c2-b28e-253792258e34",
  "updatedAt": "2019-08-24T14:15:22Z",
}
```

| Attribute         | Type                 | Description                                                                                          | Rules    |
| :---------------- | :------------------- | :--------------------------------------------------------------------------------------------------- | :------- |
| id                | string \[uuid]       | Unique identifier of the webhook                                                                     | Required |
| tradeId           | string \[uuid]       | Internal unique identifier of the Trade                                                              | Required |
| tradingAccountId  | string \[uuid]       | Unique identifier of attached trading account                                                        | Required |
| status            | enum                 | Status of the trade                                                                                  | Required |
| externalReference | string               | An optional value that can be passed in to later reference a related resource in the partner system. | Optional |
| updatedAt         | string \[stimestamp] | The timestamp with timezone for date when Payment Address was updated                                | Required |

Status enum:

```json
TradeStatus {
  submitted,
  processing,
  pending_settlement,
  pending_payout_processing,
  awaiting_funds,
  settled,
  rejected
}
```

***

### Payment Address Webhook

```json
{
  "id": "9757e4bc-f9ba-49f0-beb8-1557f308b0ee",
  "paymentAddressId": "uuid",
  "tradingAccountId": "uuid",
  "status": "pending",
  "externalReference": "2bde2e5a-7606-49c2-b28e-253792258e34",
  "updatedAt": "2019-08-24T14:15:22Z",
}
```

| Attribute         | Type                 | Description                                                                                          | Rules    |
| :---------------- | :------------------- | :--------------------------------------------------------------------------------------------------- | :------- |
| id                | string \[uuid]       | Unique identifier of the webhook                                                                     | Required |
| paymentAddressId  | string \[uuid]       | Internal unique identifier of the payment address                                                    | Required |
| recipientId       | string \[uuid]       | Id of the recipient                                                                                  | Required |
| tradingAccountId  | string \[uuid]       | Unique identifier of attached trading account                                                        | Required |
| status            | enum                 | Status of the payment address                                                                        | Required |
| externalReference | string               | An optional value that can be passed in to later reference a related resource in the partner system. | Optional |
| updatedAt         | string \[stimestamp] | The timestamp with timezone for date when Payment Address was updated                                | Required |

Status enum:

```json
PaymentAddressStatus {
  submitted,
  processing,
  rejected,
  active,
  inactive
}
```

***

### Payout Transaction Webhook

```json
{
  "id": "9757e4bc-f9ba-49f0-beb8-1557f308b0ee",
  "payoutId": "4f8fcf90-fad4-d319-0cb7-0b6f0dc323bb",
  "tradingAccountId": "72a9356c-7362-8dd9-ed9f-585274ec147f",
  "status": "released",
  "externalReference": "2bde2e5a-7606-49c2-b28e-253792258e34",
  "endToEndId": "1736980931724",
  "updatedAt": "2023-08-24T14:15:22Z",
}
```

| Attribute         | Type                 | Description                                                                                                                  | Rules    |
| :---------------- | :------------------- | :--------------------------------------------------------------------------------------------------------------------------- | :------- |
| id                | string \[uuid]       | Unique identifier of the webhook                                                                                             | Required |
| payoutId          | string \[uuid]       | Internal unique identifier of the payment transaction                                                                        | Required |
| tradingAccountId  | string \[uuid]       | Unique identifier of attached trading account                                                                                | Required |
| status            | enum                 | Status of the payment Transaction                                                                                            | Required |
| externalReference | string               | An optional value that can be passed in to later reference a related resource in the partner system.                         | Optional |
| endToEndId        | string               | Back-office reference ID for bank tracking of the end-to-end payment. Only available when a payment reaches released status. | Optional |
| updatedAt         | string \[stimestamp] | The timestamp with timezone for date when Payment Address was updated                                                        | Required |

Status enum:

```json
PayoutTransactionStatus {  
	submitted,
	processing, 
	awaiting_funds, 
	pending_trade_settlement,
	pending_release, 
	released, 
	returned, 
	rejected 
}
```

***

### Transfer Transaction Webhook

```json
{
  "id": "9757e4bc-f9ba-49f0-beb8-1557f308b0ee",
  "transferId": "4f8fcf90-fad4-d319-0cb7-0b6f0dc323bb",
  "tradingAccountId": "72a9356c-7362-8dd9-ed9f-585274ec147f",
  "status": "compliance pending",
  "externalReference": "2bde2e5a-7606-49c2-b28e-253792258e34",
  "updatedAt": "2023-08-24T14:15:22Z",
}
```

| Attribute         | Type                 | Description                                                                                          | Rules    |
| :---------------- | :------------------- | :--------------------------------------------------------------------------------------------------- | :------- |
| id                | string \[uuid]       | Unique identifier of the webhook                                                                     | Required |
| transferId        | string \[uuid]       | Internal unique identifier of the payment transaction                                                | Required |
| tradingAccountId  | string \[uuid]       | Unique identifier of attached trading account                                                        | Required |
| status            | enum                 | Status of the payment Transaction                                                                    | Required |
| externalReference | string               | An optional value that can be passed in to later reference a related resource in the partner system. | Optional |
| updatedAt         | string \[stimestamp] | The timestamp with timezone for date when Payment Address was updated                                | Required |

Status enum:

```json
TransferTransactionStatus {
	submitted,
	processing, 
	awaiting_funds, 
	pending_trade_settlement,
	pending_release, 
	released, 
	returned, 
	rejected 
}
```

***

### Payment Recipient Webhook

```json
{
"id": "string",
"tradingAccountId": "string",
"status": "pending",
"externalReference": "2bde2e5a-7606-49c2-b28e-253792258e34",
"updatedAt": "2019-08-24T14:15:22Z",
}
```

| Attribute         | Type                 | Description                                                                                          | Rules    |
| :---------------- | :------------------- | :--------------------------------------------------------------------------------------------------- | :------- |
| id                | string \[uuid]       | Unique identifier of the webhook                                                                     | Required |
| recipientId       | string \[uuid]       | Internal unique identifier of the recipient                                                          | Required |
| tradingAccountId  | string \[uuid]       | Unique identifier of attached trading account                                                        | Required |
| status            | enum                 | Status of the recipient                                                                              | Required |
| externalReference | string               | An optional value that can be passed in to later reference a related resource in the partner system. | Optional |
| updatedAt         | string \[stimestamp] | The timestamp with timezone for date when Payment Address was updated                                | Required |

Status enum:

```json
RecipientStatus {
  submitted,
  processing,
  rejected,
  active,
  inactive
}
```

## How to get Webhooks information and delete Webhook

### Fetching the information about the Webhooks

To request the information about all the **Webhooks** for the Enterprise User you can send a signed `GET /webhook` request.

In response to your request you will receive either a SUCCESS 200 response or one or the error responses (400, 401, 500) See [Status Codes & Error Messages](doc:status-codes-error-messages).

Given a valid `accessToken` a SUCCESS response will return the details for all the previously created **Webhooks**.

### Deleting the existing Webhook

To remove up the **Webhooks** for the Enterprise User you can send a signed `DEL /webhooks/{webhookId}` request.

In response to your request you will receive either a `SUCCESS 204` response or one or the error responses (400, 401, 500) See [Status Codes & Error messages](doc:status-codes-error-messages).

Subscribe to your choice of events by providing a url to receive event notification requests from the Send API.

Fetches all webhooks for an enterprise user.

<p class="slate-p " >Fetches all webhooks for an enterprise user.</p><p class="slate-p " ></p>

Authorization

The maximum number of records per page to return.

itemsPerPage

The number of the page to return. The default starting point is the UTC date time when we receive the request and the default sort order is ascending. NOTE: Records could be added or updated between request.

pageNumber

The unique identifier for the webook record.

webhookId

The URL that will receive events from the Send API.

Array of events that the URL will receive updates for.

events

description

The UTC date-time that the webhook record was created.

createdAt

The UTC date-time that the webhook record was updated.

updatedAt

status

items

Total number of records in the collection ignoring pagination. Use this to determine if records have been added or removed between calls.

itemsCount

Total number of records in the data array. The total number for a specified page may differ between requests to the same URL if an item was added or removed from the collection between requests.

Sections

/webhooks

Header Parameters

Query Parameters

Response

Response Attributes

Response Attributes

Response Attributes

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Sections

/webhooks

Header Parameters

Query Parameters

ResponseExpand all

Response Attributes

Response Attributes

Response Attributes

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Response