Introduction

The Ebury API helps you fund and manage your international business by making trading and payments easy to integrate into your applications. You choose how and where to deploy your application, and we provide the means to integrate foreign exchange and payment functionalities in them directly. The API is modular, with the following core areas of functionality:

Quotes: Get live rates, either estimated or a short-lived quote that you can use to book a trade;
Trades: Use a quote to execute a trade;
Payments: Use a trade to fund payments;
Multi Payments: Wraps trades, beneficiary management and payments into a "bulk" operation, allowing payments initiation across a number of currencies;
Account Management: Profile updates, beneficiary management, etc.

In terms of style, the API is a "pragmatic" REST + JSON API with a design approach aimed at simplicity and ease of use. A few notes:

URIs do not descend more that one i.e. /quotes, /trades, etc.;
We use links where it makes sense to convey information to our API consumers but we are not religious about full-on HATEOAS/code-on-demand style. If links help we use them;
We will version our API on major versions only, with the version number defined in the hostname , e.g. https://api-v1.ebury.io/trades;
We'll be looking to add support for Webhooks once our first production release is GA.

Getting Started

The Ebury API has been designed for ease of use, but there are a number of things that need to happen or you need to know before you can start developing against it.

Onboarding

In order to use the API your company needs to be one of the following:

To be an existing Ebury customer with access to Ebury Online;
To be on-boarded as an Ebury customer with access to Ebury Online: Currently this is an out-of-band process that needs to be completed by the Ebury sales team.

Credentials

With an active Ebury Online account you need a few details to call the API:

A client secret that is used in the Authentication workflow described below;
An access token which you will get by implementing the Authentication workflow;
A client account identifier that links a user to a given account and needs to be passed to the Authentication workflow;
You'll need to supply a redirect URL, which will be used during the Authentication workflow.

Environments

The following is a list of environments available when developing against or using our API:

Environment Endpoints

URL	Purpose
`https://sandbox.ebury.io`	Sandbox API endpoint
`https://auth-sandbox.ebury.io`	Sandbox authentication endpoint
`https://api.ebury.io`	Production API endpoint
`https://auth.ebury.io`	Production authentication endpoint
`https://trustedsandbox.ebury.io`	mTLS Sandbox (both authentication and API)
`https://trusted.ebury.io`	mTLS Production (both authentication and API)

API Description

Whilst each subject area is documented below they are also supported by an individual Swagger specification document. Please use the links below to download for your desired environment:

Environment	JSON	YAML
`Sandbox`	https://sandbox.ebury.io/openapi.json	https://sandbox.ebury.io/openapi.yaml
`Production`	https://api.ebury.io/openapi.json	https://api.ebury.io/openapi.yaml

Rate limiting

Rate limiting of the Ebury API is primarily on a per-client basis. If you receive a response with a status code of 429 Too Many Requests, it means that you have been rate limited for sending too many requests, and should wait before sending further requests.

Error Handling

The Ebury API tries to honour HTTP return codes relevant to the error that is being conveyed. However, 4xx HTTP return codes are also used as a "blanket" with more information to be found in the response body of the error message e.g., a 409 will indicate an issue with the data sent that can be rectified: you should consult this message to help you take corrective action.

Idempotency

The Ebury API is not exposing idempotent operations by default.

The POST requests can however include a header X-Idempotency-Id, to be used as a lock to gain idempotency features.

After every POST request, the response header X-Idempotency-Status is returned with the result of the idempotency logic.

This is an opt-in feature. If the header X-Idempotency-Id is not present, no extra logic is considered.

The first time the API sees a X-Idempotency-Id, it returns accepted and locks the value for 15 days.

The following times the same value is used within the first 15 days: the API will return duplicated, with status 409, and will not process the request.

We suggest using a random UUID as X-Idempotency-Id.

Summary for situations.

Request method	`X-Idempotency-Id`	Response status	`X-Idempotency-Status`	Meaning
No `POST`	Not checked	As usual	Not present	No extra logic
`POST`	Not present	As usual	`missing`	No extra logic
`POST`	Present, first time seen	As usual	`accepted`	Lock acquired for 1 day
`POST`	Present, already seen in last day	409	`duplicated`	Lock was already acquired, this request was already accepted
`POST`	Present, but the system cannot check it	503	`unavailable`	The intention was acknowledged, but the service cannot check for the idempotency

HTTP Response Codes

Response code	Meaning
`200 OK`	Request completed successfully. See individual endpoints for details of response content.
`201 Created`	Request completed successfully, and a resource was created. See individual endpoints for details of response content.
`202 Accepted`	Request completed successfully, but not completely processed. See individual endpoints for details of response content.
`400 Bad Request`	The request could not be processed due to some error e.g., formatting, parameter or schema validation. See error message for details of response content.
`401 Unauthorized`	Access denied due to authentication failure
`403 Forbidden`	Could not complete action due to data constraints. See error message for details of response content.
`404 Not Found`	The requested resource could not be found. See individual endpoints for details of how to identify resources.
`409 Conflict`	Request could not be completed. See error message for details of response content.
`429 Too Many Requests`	You have exceeded the rate limit for IP or server. See rate limiting for details.
`502 Bad Gateway`	Internal error. See error message for details of response content.
`503 Service Unavailable`	Internal error. See error message for details of response content.
`504 Gateway Timeout`	Internal timeout. See error message for details of response content.

Error Message

{
    "code": "string",
    "message": "string",
    "details": "string"
}

Error messages are presented as JSON objects.

Error Message Fields

Field	Description
`code`	A short code for the error
`message`	The error message
`details`	Error details

Authentication

The Ebury authentication scheme is based on OpenID Connect 1.0, which builds on OAuth 2.0 to make it easier to verify the identity of end users. We've chosen OpenID Connect as we believe it offers our consumers a good mix of security and flexibility and implemented that Authorization Code flow for OpenID Connect: The steps required to complete this flow are detailed in the following sections.

The diagram below shows an overview of the process when Second Factor Authentication (2FA) is disabled:

OpenID flow overview

When 2FA in enabled the process is slightly different as can be seen on the following diagram:

OpenID flow overview

Acquire an access token

Acquiring an access token is a three-step process:

Redirect the user to Ebury to authorise your app
The user authenticates with Ebury
If 2FA is enabled, the user provides the verification code on the 2FA screen
Ebury redirects the user back to your app with an authorization code
Exchange the authorization code for an access token

Redirect the user to Ebury

"https://auth.ebury.io/authenticate?
    scope=openid&
    response_type=code&
    client_id=$client_id&
    state=$state&
    redirect_uri=$redirect_uri"

To start the authentication process a request needs to be made in a browser to our authorization server to identify the application attempting to access the user's profile. This may be implemented in a mobile or web application but the access tokens can be used for server-based applications as well.

Query Parameters

Parameter	Description
`client_id` Required	Your client identifier
`scope` Required	Must be `openid`; no other values are supported
`response_type` Required	Must be `code`
`state` Required	A random, per request value used to maintain state between request and callbacks and protect against cross-site request forgery attacks
`redirect_uri` Required	The redirect URL that is registered for your application, this must match the value we hold

User Authentication

If all parameters are successfully validated the Authorization Server will present an Ebury login screen. The user will be required to enter their Ebury Online email address and password, as shown below.

Ebury redirects back to your app

HTTP/1.1 302 Found
Location: https://your.redirect.url/?code=$authorization_code&state=$state_token

Once the credentials have been successfully entered, one of two things can happen:

If the user does not have Second Factor Authentication (2FA) enabled, the authentication process is completed (Authentication completed)
If the user has 2FA enabled, go to Second Factor Authentication

Second Factor Authentication

If the user has 2FA enabled, it will be redirected to the 2FA screen and will be issued a 2FA code (SMS/TOTP are supported for now). The user will be required to enter this code, as shown below:

2FA Screen

If the verification code was entered correctly then the authentication process is completed (Authentication completed)

Query Parameters

Parameter	Description
`code` Required	Value returned by authorization endpoint
`client_id` Required	Your client identifier

Authentication completed

After the authentication process is completed, the user will be redirected to the redirect_uri registered for the application. The following querystring parameters will be included:

Response Parameters

Parameter	Description
`code`	A code that allows your application to call the Token Endpoint to complete the OpenID flow
`state`	Value passed from your application in the original authorization request

Exchange the authorization code

curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic bGV0c3ByZXRlbnQ6aXNhdGFuZW5kCg==" \
https://auth.ebury.io/token \
--data 'grant_type=authorization_code&code=$code&redirect_uri=$redirect_uri'

Response

{
  "token_type": "Bearer",
  "access_token": "XKtOK3hNzKpLkaom3J2MEPyKm7f7jZ",
  "refresh_token": "2E9KVBXgVzQSPTvoHjJB1Eu2eBjzup",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiAiSFMyNTYifQ==.ewogICJhdWQiOiAiWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFgiLAogICJzdWIiOiAiWFhYWFhYWFhYWFgiLAogICJpc3MiOiAiaHR0cHM6Ly9hdXRoLmVidXJ5LmlvIiwKICAiaWF0IjogIjE0NjQyNjY2MzkiLAogICJjbGllbnRzIjogWwogICAgIlhYWFhYWFhYWFhYIgogIF0sCiAgImV4cCI6ICIxNDY0MzUzMDM5Igp9Cg==.bkieHxES1spJnVmDmhganElaP6LZfikKXZ8uphVQwUo"
}

The final step is for your application to exchange the authorisation code for an access token that will provide access to the API. This must happen within 10 minutes of receiving your authorisation code. The following parameters are passed to the token endpoint

Query Parameters

Parameter	Description
`grant_type` Required	Must be set to `authorization_code`
`code` Required	Value returned by authorization endpoint
`redirect_uri` Required	The redirect URL that is registered for your application, this must match the value we hold

If the all parameters are correct a response will be returned containing the following:

Response Fields

Field	Description
`token_type`	The Authorization header scheme to use when making requests, will be `Bearer`
`access_token`	An OAuth access token that can be used to call the API
`refresh_token`	An OAuth refresh token that can be used to get a new access token when when the last expires
`expires_in`	Expiry period in seconds from time token returned, currently returns `3600` (1 hour)
`id_token`	A signed, base 64 encoded JSON Web Token that provides verification of the identity that authorized the request. The token includes the client identifier, which is a required parameter on the majority of API calls.

Decoded JSON Web Token (without signature)

{
  "alg": "HS256"
}
{
  "aud": "XXXXXXXXXXXXXXXXXXXXXXXXXX",
  "sub": "XXXXXXXXXXX",
  "iss": "https://auth.ebury.io",
  "iat": "1464266639",
  "clients": [{
      "client_id": "XXXXXXXXXXX",
      "client_name": "Example client name"
  }],
  "exp": "1464353039"
}

Sample code for extracting data from the JSON Web Token

var jsonData = JSON.parse(responseBody);

token = jsonData["access_token"];
postman.setEnvironmentVariable("token", token);

idtoken = parseJwt(jsonData["id_token"]);
postman.setEnvironmentVariable("contact_id", idtoken["sub"]);

clients = idtoken["clients"];
postman.setEnvironmentVariable("client_id", clients[0].client_id);

/*function to decode JSON web token*/
function parseJwt(token) {
  var base64Url = token.split(".")[1];
  var base64 = base64Url.replace("-", "+").replace("_", "/");
  return JSON.parse(atob(base64));
}

By decoding this token we can get the value for client_id needed for future requests.

An array of client_id and client_name lists the potential clients that the contact can act on behalf of. The majority of customers will only have one client identifier, but some may have multiple client accounts and thus multiple identifiers that the contact can act on

The client_id is required in query params of requests post authentication in order to identify the client to which the request is on behalf of. Your application may have to allow a contact to select the correct client_id to use.

Refreshing access

curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic $access_token" \
https://auth.ebury.io/token \
--data 'grant_type=refresh_token&refresh_token=$refresh_token&scope=openid'

Your access token will expire according to the value set in the Exchange the authorisation code response, but you can directly get a new access token by using your refresh token without needing to restart the authentication from the start. Our OpenID Provider conforms to the refresh token mechanism described here. The refresh token lifespan is configurable depending on the client's needs.

Request Fields

Field	Description
`grant_type` Required	Should be `refresh_token`
`refresh_token` Required	One of the last 10 refresh tokens, issued within the last 'n' days. Where 'n' is the refresh token lifespan agreed with the client (default value is 28 days).
`scope` Required	Should be `openid`

If successful, the response will contain the same data as the original access token response.

Getting an access token on behalf of a client

It is possible for financial institutions to get an access token on behalf of their clients by using the contact id of the client.

This functionality is not available per default, you need to contact Ebury to enable it for each contact you need an access token for.

This endpoint is only available using mTLS.

curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic $access_token" \
https://trusted.ebury.io/token/$contact_id \
--data 'grant_type=client_credentials'
--cert fullchain.pem \
--key privkey.pem

Path Parameters

Parameter	Description
`contact_id` Required	The contact identifier

Request Fields

Field	Description
`grant_type` Required	Should be `client_credentials`

If successful, the response will contain the access token response.

Authenticating requests

GET /example-endpoint HTTP/1.1
Authorization: Bearer your-access-token

All requests must be authenticated with an access token.

Almost all requests will accept an optional Ebury user identifier, set in the X-Contact-Id header.

The X-Contact-Id header used to be a requirement, but you can safely drop it from your requests and you should do so if possible. If present, it will be checked for equality with the contact id that is making the request.

Request Headers

Header	Description
`Authorization` Required	Your access token, prefixed with the `Bearer` scheme
`x-api-key`	Your API key (Deprecated)
`X-Contact-Id` Optional	Identifier for an Ebury user (Deprecated)

Trusted authentication

By default when a client connects to a server over HTTPS only the identity of the server is verified.

Ebury supports verifying the identity of the client as well by using a client certificate.

To use this functionality you need to connect using these URLs instead of the ones you usually use.

Environment	Hostname
`Sandbox`	https://trustedsandbox.ebury.io
`Production`	https://trusted.ebury.io

Also, note that you will use these endpoints for both authentication and API access. For example:

To retrieve an access token in the sandbox environment you would call https://trustedsandbox.ebury.io/token instead of https://auth.ebury.io/token
To create a payment in the sandbox environment you would call https://trustedsandbox.ebury.io/payments instead of https://api.ebury.io/payments

In order to use this functionality you need to provide Ebury with the subject distinguished name of the certificate you will be using to connect because we will match the subject DN you provide with the subject DN of the client's certificate used during the connection.

In order to check the validity of the client certificate you will be using to connect to and also to get the Subject DN of your certificate you can use the check_cert endpoint.

curl --cert fullchain.pem --key privkey.pem https://trustedsandbox.ebury.io/cert_check

package main

import (
    "crypto/tls"
    "io/ioutil"
    "net/http"
    "log"
    "strings"
)

func main() {
    cert, err := tls.LoadX509KeyPair("fullchain.pem",
                                     "privkey.pem")
    if err != nil {
        log.Fatal(err)
    }

    tlsConfig := &tls.Config{
        Certificates:       []tls.Certificate{cert},
        MinVersion:         tls.VersionTLS13,
    }
    tlsConfig.BuildNameToCertificate()
    transport := &http.Transport{TLSClientConfig: tlsConfig}

    req, err := http.NewRequest("GET", "https://trustedsandbox.ebury.io/cert_check", strings.NewReader(""))
    if err != nil {
        log.Fatal(err)
    }

    client := &http.Client{Transport: transport}
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }

    contents, err := ioutil.ReadAll(resp.Body)
    log.Println(string(contents))
}

#!/usr/bin/php
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSLCERT, 'fullchain.pem');
curl_setopt($ch, CURLOPT_SSLKEY, 'privkey.pem');
curl_setopt($ch, CURLOPT_VERBOSE, true);
curl_setopt($ch, CURLOPT_URL,'https://trustedsandbox.ebury.io/cert_check');
$result=curl_exec($ch);
echo $result;

?>

import requests

response = requests.get('https://trustedsandbox.ebury.io/cert_check', cert=("fullchain.pem", "privkey.pem"))

print(response.text)

Response

CN=81be95eb.ngrok.io

If everything goes fine you will get a 200 response and the content of the response will be the subject DN of the certificate. You can now share the subject DN of the certificate with Ebury and the trusted connection with the regular endpoints will work without any further changes.

On the other hand, if there is a problem with the certificate or connection you might get one of these errors.

Status Code	Error
`495`	The certificate provided is invalid or the provided certificate's Subject DN does not matches the one for the client.
`496`	There was not certificate provided.
`497`	The connection was made using HTTP instead of HTTPS.

You can check the next section in order to troubleshoot the issue.

Troubleshooting

In order to use this functionality the client you are connecting with must support the TLS 1.3 protocol, we don't support older versions of the protocol.

You need at least OpenSSL 1.1.1 in order to be able to use TLS 1.3, to check your openssl version you can use:

openssl version

Also, the connection must be done by using any of the following ciphers:

TLS_AES_128_GCM_SHA256
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256

You can check the ciphers supported by doing:

openssl ciphers -v | grep TLSv1.3

If you can run any of these commands and get a successfull verification you are good to go

openssl s_client -tls1_3 -ciphersuites 'TLS_AES_128_GCM_SHA256' -connect tls13.cloudflare.com:443

openssl s_client -tls1_3 -ciphersuites 'TLS_AES_256_GCM_SHA384' -connect tls13.cloudflare.com:443

openssl s_client -tls1_3 -ciphersuites 'TLS_CHACHA20_POLY1305_SHA256' -connect tls13.cloudflare.com:443

Example Workflow

If you follow the Authentication guidelines you'll have implemented the means to access the API. The following sections describe how to secure a trade, add a beneficiary and make a payment. For more detail on each of these activities please see the relevant sections.

Get a Quote

curl -X POST \
"https://api.ebury.io/quotes?quote_type=quote&client_id=$client_id" \
-H "Authorization: Bearer $access_token" \
-H "Content-Type: application/json" \
-d '{
        "trade_type": "spot",
        "buy_currency": "EUR",
        "amount": 1500.0,
        "operation": "buy",
        "sell_currency": "GBP",
        "value_date": "2016-09-20"
}'

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "book_trade": "/trades?client_id=TAICLI00003&quote_id=9ff9aee7a6d5f5e1b797165ffe580d74",
  "buy_amount": 1500.0,
  "buy_currency": "EUR",
  "inverse_rate": 0.910995,
  "inverse_rate_symbol": "GBPEUR",
  "quote_id": "9ff9aee7a6d5f5e1b797165ffe580d74",
  "quoted_rate": 1.097701,
  "quoted_rate_symbol": "EURGBP",
  "sell_amount": 1366.49,
  "sell_currency": "GBP",
  "value_date": "2016-10-27"
}

To execute a trade, you need to call the Quotes endpoint and get a quote. As already discussed in Getting Started to get a quote you need the following:

The authentication flow completed with an access token to hand;
The correct client identifier, retrieved from the ID token generated by the Token endpoint.

The response contains a quote_id and a URL that you can use to book the trade. For more details on the Quotes API please refer to the Getting Quotes section.

Client Identifier

The client identifier is an entity Ebury uses to differentiate between different accounts in our data model. Majority of customers will only have one client identifier, but some may have multiple accounts and thus multiple identifiers.

Book a Trade

curl -X POST \
"https://api.ebury.io/trades?quote_id=$quote_id&client_id=$client_id" \
-H "Authorization: Bearer $access_token" \
-H "Content-Type: application/json" \
-d '{
        "reason": "Travel costs",
        "trade_type": "spot"
}'

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "bank_account": {
    "account_number": "99999999",
    "iban": "GB99TEST999999999999",
    "swift_code": "TESTGB99",
    "bank_identifier": "999999",
    "bank_identifier_type": "GBP Sort Code",
    "bank_name": "Name of the Bank",
    "bank_address_line_1": "123 Sesame Street",
    "bank_address_line_2": "Apartment 01-02",
    "bank_city": "London",
    "bank_post_code": "SW1W9QB"
  },
  "trade_id": "EBPOTR432737",
  "maturiy_date": "2016-10-29T15:30:00.52Z"
}

With the quote identifier you can now book a trade to fund payment, calling the trades endpoint. Due to anti-money laundering a reason for making the trade needs to be specified; the API allows this to be a freeform value at the time of writing but future versions may introduce validation of the reason submitted.

The response contains a trade_id you can now book payments for known beneficiaries. For more details on the Trades API please refer to the Making Trades section.

Add a Beneficiary

curl -X POST \
"https://api.ebury.io/beneficiaries?client_id=$client_id" \
-H "Authorization: Bearer $access_token" \
-H "Content-Type: application/json" \
-d '{
  "name": "John Doe",
  "email_notification": true,
  "address_line_1": "123 Sesame Street",
  "post_code": "456",
  "country_code": "GB",
  "bank_country_code": "GB",
  "bank_currency_code": "GBP",
  "account_number": "99999998",
  "swift_code": "TESTGBGB999",
  "iban": "TESTGBGB9999999999",
}'

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "active": "True",
  "address_line_1": null,
  "aml_status": "Not Checked",
  "bank_accounts": [
    {
      "account_id": 9999,
      "account_number": "99999998",
      "bank_address_line_1": null,
      "bank_country_code": "GB",
      "bank_currency_code": "GBP",
      "bank_identifier": null,
      "bank_name": null,
      "correspondent_account": null,
      "correspondent_swift_code": null,
      "iban": "TESTGBGB9999999999",
      "swift_code": "TESTGBGB999"
    }
  ],
  "beneficiary_id": "EBPBEN999999",
  "country_code": "GB",
  "created": "2016-10-25",
  "email_addresses": [],
  "email_notification": true,
  "name": "John Doe",
  "post_code": null
}

With the trade booked you can create a beneficiary who will be the recipient of part or all of the trade (of course you only need to create a beneficiary once, they are stored and can be reused later).

A beneficiary ID and account ID are returned that you can use to make a payment. For more details on the Beneficiaries API please refer to the Managing Beneficiaries section.

Make a Payment

curl -X POST \
"https://api.ebury.io/payments?client_id=$client_id" \
-H "Authorization: Bearer $access_token" \
-H "Content-Type: application/json" \
-d '{
    "trade_id": "EBPOTR999999",
    "async": false,
    "payments":[
        {
            "beneficiary_id": "EBPBEN999999",
            "account_id": "99999",
            "amount": 10.50,
            "payment_date": "2016-10-30",
            "reference": "2016-10-29",
            "email_beneficiary": true
        }
    ]
}'

Response

HTTP/1.1 201 Created
Content-Type: application/json

[
  {
    "payment_id": "PI999999",
    "payment_instruction": "/documents?type=pi&id=PI999999&client_id=TAICLI00003",
    "payment_receipt": "Not available",
    "status": "Validating beneficiary information"
  }
]

Everything is now in place to book on or more payments, using the trade_id and beneficiary and account IDs returned from the create beneficiary step.

A payment_id will be returned together with links to download the payment instruction and receipt documents when available; if you are set-up to to pay immediately the payment will be made when:

The beneficiary is validated;
Funds are available;
The payment date is reached.

If the payment requires authorisation an additional PATCH method will be required; refer to the notes in the Making Payments section for details.

Clients

Get Clients

Retrieve the list of clients which a contact can access, including their brands and status.

Request Headers

GET /clients HTTP/1.1
Authorization: string

Query Parameters

Name	Field Type	Location	Max Length	Accepted Values	Mandatory	Additional Info
`page`	`integer`	`query`		`>=1`	`N`	The desired page number for pagination. Default value is `1`
`page_size`	`integer`	`query`		`>=1`	`N`	The number of items per page for pagination. Default value is `50`

Response

[
    {
        "brand_name": "Ebury",
        "client_id": "EBPCLI285330",
        "client_name": "Ebury Partners UK",
        "status": "Active"
    },
    {
        "brand_name": "Ebury",
        "client_id": "EBPCLI285313",
        "client_name": "Ebury Partners ES",
        "status": "Active"
    },
    {
        "brand_name": "Ebury",
        "client_id": "EBPCLI285314",
        "client_name": "Ebury Partners BE",
        "status": "Active"
    }
]

A successful request will return a 200 OK response with a response body consisting of an array of objects with the following fields:

Name	Field Type	Location	Additional Info
`content-type`	`application/json`	`header`
`x-total-count`	`integer`	`header`	Total number of entries returned.
`content-length`	`string`	`header`
`brand_name`	`string`	`body`	The brand of the client (e.g. Ebury).
`client_id`	`string`	`body`	The client identificator (e.g. EBPCLIXXXX).
`client_name`	`string`	`body`	The name of the client.
`status`	`string`	`body`	It can be: “Active”, “Inactive”, “Closed” or “Blocked”.

Getting Quotes

Get an estimate or firm quote:

An estimate is as it's described: the current rates on offer within the Ebury platform with no firm quote;
A firm quote returns a reference (a quote_id) that can be used to book a trade.

Get an estimate or firm quote

POST /quotes?client_id=$client_id&quote_type=$quote_type HTTP/1.1
Authorization: string

Content-Type: application/json

{
    "trade_type": "string",
    "sell_currency": "string",
    "buy_currency": "string",
    "amount": "number",
    "operation": "string",
    "value_date": "string"
}

Obtain either an estimate or firm quote; estimates are for reference only, while a firm quote can be used to book a trade.

Request Headers

Header	Description
`Content-Type` Required	`application/json`

Query Parameters

Parameter	Description
`quote_type` Required	The type of quote you are requesting. Acceptable values: `estimate` (for reference only) `quote` (valid only for a short window of time and required to book a trade)
`client_id` Required	The client identifier you are requesting this quote for

Request Body

Field	Description
`trade_type` Required	The type of trade you require a quote for. Acceptable values: `spot` `forward`
`sell_currency` Required	Sell currency
`buy_currency` Required	Buy currency
`amount` Required	Amount in `double` format
`operation` Required	The operation you want to perform. Acceptable values: `buy` `sell`
`value_date`	The date you want the quote. If the value date is not provided or is invalid then the quote will be returned for next available value date.

Estimate Quote Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "estimated_rate": "number",
    "estimated_rate_symbol": "string",
    "inverse_rate": "number",
    "inverse_rate_symbol": "string",
    "fee_amount": "number",
    "fee_currency": "string",
    "value_date": "string",
    "warning": "string"
}

Quote requests with a quote_type of estimate will return a 200 OK response with the following response body.

Fields

Field	Description
`estimated_rate` Always	The estimated rate
`estimated_rate_symbol` Always	The symbol of estimated rate
`inverse_rate` Always	Inverse rate
`inverse_rate_symbol` Always	The symbol of inverse rate
`fee_amount` Always	Fee amount
`fee_currency` Always	Fee currency
`value_date` Always	Date on which quote is requested
`warning`	A warning is only returned if the requested value date was not valid and the next available date has been returned.

Firm Quote Response

HTTP/1.1 201 Created
Content-Type: application/json

{
    "quote_id": "string",
    "sell_currency": "string",
    "sell_amount": "number",
    "buy_currency": "string",
    "buy_amount": "number",
    "quoted_rate": "number",
    "quoted_rate_symbol": "string",
    "inverse_rate": "number",
    "inverse_rate_symbol": "string",
    "value_date": "string",
    "book_trade": "string",
    "warning": "string"
}

Quote requests with a quote_type of quote will return a 201 Created response with the following response body.

Fields

Field	Description
`quote_id` Always	Quote identifier. Used to create book a trade at the Trades endpoint
`sell_currency` Always	Sell currency
`sell_amount` Always	Sell amount
`buy_currency` Always	Buy currency
`buy_amount` Always	Buy amount
`quoted_rate` Always	The rate quoted
`quoted_rate_symbol` Always	The symbol of rate quoted
`inverse_rate` Always	The inverse rate
`inverse_rate_symbol` Always	The symbol of inverse rate
`value_date` Always	Date on which trade active
`book_trade`	Call this endpoint to book the trade (refer to Trades documentation for required payload)
`warning`	A warning is only returned if the requested value date was not valid and the next available date has been returned.

Get FX markets availability

curl --location --request GET '/quotes/fx-availability?client_id=XXXXXX' \
--header 'Authorization: $token' \
--header 'Content-Type: application/json'

import requests
import json

url = "/quotes/fx-availability?client_id=XXXXXX"

payload={}
headers = {
  'Authorization': token,
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "/quotes/fx-availability?client_id=XXXXXX"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", token)
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

<?php
#!/usr/bin/php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => '/quotes/fx-availability?client_id=XXXXXX',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: $token',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

The endpoint can be used to understand if foreign exchange can be initiated at that time or not. It is useful in instances which want to proactively manage whether or not to allow the user to attempt FX rather than throwing an error after the FX initiation request.

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Response

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "fx_available": "boolean",
}

A successful request will return a 200 OK response with the following response body.

Fields

Name	Description
`fx_available` ALWAYS	True if the FX market is available for creating quote and trades. False if otherwise.

Making Trades

Create a Trade

POST /trades?client_id=$client_id&quote_id=$quote_id HTTP/1.1
Authorization: string
Content-Type: application/json

{
    "reference": "string",
    "reason": "string",
    "external_reference_id": "string",
    "convert": "boolean"
}

Initiate a new trade.

You need to have an valid quote_id from a firm quote response to create a trade.

Request Headers

Header	Description
`Content-Type` Required	`application/json`

Query Parameters

Parameter	Description
`quote_id` Required	The identifier of the quote, obtained from making a firm quote
`client_id` Required	The ID of the client

Request Body

Fields

Name	Description
`reason` Required	Reason for trade. See ReasonForTradeValues for acceptable values.
`reference`	Reference for the trade.
`external_reference_id`	API external reference id for the trade.
`convert`	Intention behind the trade. When set to `true`, trade will be executed and funds will be transferred between two Ebury wallets. When `false`, trade will be executed only when it is linked to at least one payment. By default, the field is set to `false`.

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
    "trade_id": "string",
    "bank_account": {
        "account_number": "string",
        "iban": "string",
        "swift_code": "string",
        "bank_identifier": "string",
        "bank_identifier_type": "string",
        "bank_name": "string",
        "bank_address_line_1": "string",
        "bank_address_line_2": "string",
        "bank_city": "string",
        "bank_post_code": "string"
    },
    "maturity_date": "string",
    "initial_margin_amount": "number",
    "initial_margin_due_date": "string"
}

A successfully created trade will return a 201 Created response with the following response body.

Fields

Name	Description
`trade_id` Required	Trade identifier
`bank_account` Required	An existing bank account
`maturity_date` Required	Limit date and time (UTC) in which funds must be received by Ebury
`initial_margin_amount`	Only for forwards. Trade's deposit amount
`initial_margin_due_date`	Only for forwards. Date on or before which deposit must be received by Ebury. Date and time are in UTC.

Get all trades

GET /trades?client_id=$client_id HTTP/1.1
Authorization: string

Get all the trades for a given client ID.

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`trade_type`	Filter the response to include only trades with a matching type, which are specified by an `array[string]` Acceptable values: `spot` `forward` `window_forward` `drawdown` `ndf`
`parent_trade_id`	Parent identifier for drawdown trades
`page`	The desired page number for pagination. Default value is `1`.
`page_size`	The number of items per page for pagination. Default value is `50`.
`mass_payment_id`	Filter by related mass payment's uuid.
`mass_payment_external_reference_id`	Filter by related mass payment's external reference.
`buy_currency`	Filter by buy currency.
`status`	Filter trade by statuses. Separated by comma Acceptable values: `Created` `Funds In Partially` `Funds In Full` `Funds Out Partially Allocated` `Closed` `Cancelled`
`external_reference_id`	Filter by API external reference id.
`from_maturity_date`	Only return trades with trade maturity date on or after the from_maturity_date. YYYY-MM-DD format.
`to_maturity_date`	Only return trades with trade maturity date on or before the to_maturity_date. YYYY-MM-DD format.
`from_order_date`	Only return trades with trade order date on or after the from_order_date. YYYY-MM-DD format.
`to_order_date`	Only return trades with trade order date on or before the to_order_date. YYYY-MM-DD format.

Response

HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1

[
    {
        "trade_id": "string",
        "trade_type": "string",
        "status": "string",
        "buy_currency": "string",
        "buy_amount": "number",
        "sell_currency": "string",
        "sell_amount": "number",
        "rate": "number",
        "rate_symbol": "string",
        "order_date": "string",
        "maturity_date": "string",
        "fee_currency": "string",
        "fee_amount": "number",
        "synthetic": "boolean",
        "trade_receipt": "string",
        "reference": "string",
        "parent_trade_id": "string"
    }
]

A successful request will return a 200 OK response with the response body containing a list of trade objects presented with the BookedTrade model. In addition the total number of entries is available in the header field x-total-count.

Get a trade

GET /trades/$trade_id?client_id=$client_id HTTP/1.1
Authorization: string

Get a trade with a specific trade_id.

Path Parameters

Parameter	Description
`trade_id` Required	Trade identifier

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "trade_id": "string",
    "trade_type": "string",
    "status": "string",
    "buy_currency": "string",
    "buy_amount": "number",
    "sell_currency": "string",
    "sell_amount": "number",
    "rate": "number",
    "rate_symbol": "string",
    "order_date": "string",
    "maturity_date": "string",
    "fee_currency": "string",
    "fee_amount": "number",
    "synthetic": "boolean",
    "parent_trade_id": "string",
    "trade_receipt": "string",
    "reference": "string"
}

A successful request will return a 200 OK response with the requested trade object in response body presented with the BookedTrade model.

Trade Models

These models are returned by the get all trades and get a trade endpoints.

BookedTrade

{
    "trade_id": "string",
    "trade_type": "string",
    "status": "string",
    "buy_currency": "string",
    "buy_amount": "number",
    "sell_currency": "string",
    "sell_amount": "number",
    "rate": "number",
    "rate_symbol": "string",
    "order_date": "string",
    "maturity_date": "string",
    "fee_currency": "string",
    "fee_amount": "number",
    "synthetic": "boolean",
    "parent_trade_id": "string",
    "trade_receipt": "string",
    "reference": "string",
    "convert": "boolean"
}

This model is a representation of a booked trade.

Fields

Name	Description
`trade_id` Always	Trade identifier
`trade_type` Always	Trade type
`status` Always	Status of the trade
`buy_currency` Always	Buy currency code
`buy_amount` Always	Buy amount
`sell_currency` Always	Sell currency code
`sell_amount` Always	Sell amount
`rate` Always	Booked rate
`rate_symbol` Always	The symbol of booked rate
`order_date` Always	Order date
`maturity_date` Always	Limit date and time (UTC) in which funds must be received by Ebury
`fee_currency` Always	Fee currency
`fee_amount` Always	Fee amount
`parent_trade_id` Always	Parent trade ID (not `null` for drawdown trades)
`synthetic` Always	Identifies as a synthetic future contracts
`trade_receipt`	The URL to get the trade receipt
`reference`	Additional trade reference e.g., invoice number
`convert`	Intention behind the trade (either to move funds internally between Ebury wallets or to link payments to trades)

TradeStatus

This is an enumeration of the status of a trade, and can be found in the BookedTrade model.

Values

Value	Description
`Created`	Trade has been created
`Funds In Partially`	The trade has been partially funded
`Funds in Full`	The trade has been fully funded
`Funds Out Partially Allocated`	The proceeds of the trade have been only partially allocated to payments out
`Funds Out Full Allocated`	The proceeds of the trade have been fully allocated to payments out
`Closed`	The proceeds of the trade have been fully paid out and the trade is closed
`Cancelled`	The trade has been cancelled

ReasonForTradeValues

This is list of acceptable values for the reason field when creating a trade.

Values

Value	Description
`charitable_aid`	Charitable Aid
`payment_for_goods`	Payment for identifiable goods
`capital_investment`	Direct capital investment in an enterprise
`payment_for_services`	Payment for identifiable services
`repatriation_of_goods`	Repatriation of sale of identifiable goods
`repatriation_of_services`	Repatriation of sale of identifiable services
`property_purchase`	Property purchase
`mortage_repayment`	Mortage repayment
`property_rental_or_maintenance`	Property rental/maintenance
`salary_payroll`	Salary/Payroll
`travel_costs`	Travel costs
`living_costs`	Living costs
`repayment_of_loan`	Repayment of a loan
`balance_hedging`	Balance sheet hedging
`repatriation_from_investment`	Repatriation of revenues from investments
`portfolio_netting`	Portfolio netting
`not_related_to_goods_or_services`	Other not related to identifiable goods or services (only Spot type)
`other`	Other

Getting Metadata

The Metadata endpoints provide the following information:

A full list of supported currencies;
A digest of the requirements for provisioning beneficiaries

Get beneficiary metadata

GET /metadata/beneficiary HTTP/1.1
Authorization: string

Describes the fields required to provision a valid beneficiary for a given country/currency combination:

All supported countries are described by this API;
For each supported country, any currency that has specific requirements is defined in the currencies list. If there are no specific requirements the value default should be used.
The response of this endpoint is in line with the SWIFT ISO20022 standards. Please note, the mandatory fields and business rules around beneficiary address defined via this endpoint, does not apply to Ebury Mass Payments customers. Should you have any doubts, please reach out to us.

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "country": "string",
        "currencies": [
            {
                "currency": "string",
                "mandatory": [
                    [
                        "string"
                    ]
                ],
                "optional_data": [
                    "string"
                ]
            }
        ],
        "reason_required": "boolean"
    }
]

A successful request will return a 200 OK response with a response body consisting of a list of the following objects.

Fields

Name	Description
`country`	Two-letter country identifier
`currencies`	List of currency objects; will contain at least one `default` object
`currencies.currency`	Currency symbol
`currencies.mandatory`	List of mandatory field combinations; combinations are presented as lists
`currencies.optional`	List of optional fields
`reason_required`	`boolean` flag

Get currency metadata

GET /metadata/currency HTTP/1.1
Authorization: string

Describe a currency

Query Parameters

Parameter	Description
`data_only`	Exclude `reason_required` flag from response; Defaults to `false`

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "currency": "string",
        "buy": {
            "cutoff_days": "integer",
            "cutoff_time": "string"
        },
        "reason_required": "boolean",
        "sell": {
            "cutoff_days": "integer",
            "cutoff_time": "string"
        },
        "invalid_value_dates": {
            "YYYY-MM-DD": "string"
        }
    }
]

A successful request will return a 200 OK response with a response body consisting of a list of the following objects.

Fields

Name	Description
`buy`	Information of this currency if it is used as "buy" currency
`buy.cutoff_days`	Cutoff days of the currency
`buy.cutoff_time`	Cutoff time for the currency in GMT/UTC
`currency`	Currency symbol
`invalid_value_dates`	Invalid trading dates and their reasons
`invalid_value_dates.YYYY-MM-DD`	Invalid trading date; the value of this key is the reason the date is invalid
`reason_required`	Show if reason required for this currency is mandatory
`sell`	Information of this currency if it is used as "sell" currency
`sell.cutoff_days`	Cutoff days of the currency
`sell.cutoff_time`	Cutoff time for the currency in GMT/UTC

Managing Beneficiaries

Create a new beneficiary

POST /beneficiaries?client_id=$client_id HTTP/1.1
Authorization: string

Content-Type: application/json

{
  "name": "string",
  "email_addresses": [
    "string"
  ],
  "email_notification": "boolean",
  "address_line_1": "string",
  "street_name": "string",
  "building_number": "string",
  "floor": "string",
  "apartment_office_number": "string",
  "city": "string",
  "state_region": "string",
  "post_code": "string",
  "country_code": "string",
  "account_number": "string",
  "bank_address_line_1": "string",
  "bank_country_code": "string",
  "bank_currency_code": "string",
  "bank_identifier": "string",
  "bank_name": "string",
  "correspondent_account": "string",
  "correspondent_swift_code": "string",
  "iban": "string",
  "inn": "string",
  "kbk": "string",
  "kio": "string",
  "kpp": "string",
  "purpose_of_payment": "string",
  "reason_for_trade": "string",
  "reference_information": "string",
  "beneficiary_reference": "string",
  "russian_central_bank_account": "string",
  "swift_code": "string",
  "vo": "string"
}

Create a new client beneficiary. Beneficiary will require verification before payments can be made

Request Headers

Header	Description
`Content-Type` Required	`application/json`

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Request Body

Fields

Name	Description
`name` Required	The name of the beneficiary
`email_addresses`	List of email addresses
`email_notification` Required	Whether the beneficiary should receive email notification of payments
`address_line_1`^*	The first address line of the beneficiary (deprecated)*
`street_name`^*	The street name of the beneficiary
`building_number`^*	The building number of the beneficiary
`floor`^*	The floor of the beneficiary
`apartment_office_number`^*	The apartment/office number of the beneficiary
`city`^* Required	The city of the beneficiary
`state_region`^*	The state/region of the beneficiary
`post_code`	The postcode of the beneficiary
`country_code` Required	The ISO 3166-1 alpha-2 code of the beneficiary's country
`account_number`	The account number of the bank account
`bank_address_line_1`	The first address line of the bank
`bank_country_code` Required	The ISO 3166-1 alpha-2 code of the bank's country
`bank_currency_code` Required	The ISO 4217 code of the bank account's currency
`bank_identifier`	The identifier of the bank
`bank_name`	Name of the bank account holder
`correspondent_account`	The account for the correspondent account of the bank
`correspondent_swift_code`	The SWIFT code for the correspondent account of the bank
`iban`	The IBAN of the bank account
`inn`	Unique Taxpayer Personal Identification Number for legal entities registered in Russia.
`kbk`	The KBK of the bank account
`kio`	Tax ID for foreign legal entities in Russia.
`kpp`	The KPP of the bank account
`purpose_of_payment`	The purpose of payment is mandatory when the beneficiary account has specific currency types. See the section PurposeOfPayment for the currencies and their acceptable values.
`reason_for_trade`	The reason for trade of the bank account
`reference_information`	The reference information which will be used as the default payment reference during payment initiation.
`beneficiary_reference`	Unique external reference ID submitted by the client for the beneficiary.
`russian_central_bank_account`	20-digit code for Russian banks.
`swift_code`	The SWIFT code of the bank account
`vo`	Code of currency transaction established by the Central Bank of Russia to describe the purpose of the payment.

* This field and the related rule becomes operational from October 2024. Further communication will follow over emails. Please note, it does not apply to Ebury Mass Payments customers in Production.

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "name": "string",
  "email_addresses": [
    "string"
  ],
  "email_notification": "boolean",
  "address_line_1": "string",
  "street_name": "string",
  "building_number": "string",
  "floor": "string",
  "apartment_office_number": "string",
  "city": "string",
  "state_region": "string",
  "post_code": "string",
  "country_code": "string",
  "bank_accounts": [
    {
      "account_number": "string",
      "bank_address_line_1": "string",
      "bank_country_code": "string",
      "bank_currency_code": "string",
      "bank_identifier": "string",
      "bank_identifier_type": "string",
      "bank_name": "string",
      "correspondent_account": "string",
      "correspondent_swift_code": "string",
      "iban": "string",
      "inn": "string",
      "kbk": "string",
      "kio": "string",
      "kpp": "string",
      "reason_for_trade": "string",
      "reference_information": "string",
      "russian_central_bank_account": "string",
      "swift_code": "string",
      "vo": "string",
      "account_id": "integer"
    }
  ],
  "beneficiary_id": "string",
  "created": "string",
  "aml_status": "string",
  "active": "string",
  "beneficiary_reference": "string",
}

A successful request will return a 201 Created response with the response body containing a Beneficiary object.

Get beneficiaries

GET /beneficiaries?client_id=$client_id HTTP/1.1
Authorization: string

Get all beneficiaries for a given client

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`page`	The desired page number for pagination. Default value is `1`.
`page_size`	The number of items per page for pagination. Default value is `50`.
`iban`	The IBAN of the beneficiary.
`account_number`	The account number of the beneficiary.
`bank_currency_code`	The currency of the beneficiary's account.
`bank_identifier`	The bank identifier of the beneficiary's account.
`beneficiary_reference`	Unique external reference ID submitted by the client for the beneficiary.

Response

HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1

[
  {
    "name": "string",
    "email_addresses": [
      "string"
    ],
    "email_notification": "boolean",
    "address_line_1": "string",
    "street_name": "string",
    "building_number": "string",
    "floor": "string",
    "apartment_office_number": "string",
    "city": "string",
    "state_region": "string",
    "post_code": "string",
    "country_code": "string",
    "bank_accounts": [
      {
        "account_number": "string",
        "bank_address_line_1": "string",
        "bank_country_code": "string",
        "bank_currency_code": "string",
        "bank_identifier": "string",
        "bank_identifier_type": "string",
        "bank_name": "string",
        "correspondent_account": "string",
        "correspondent_swift_code": "string",
        "iban": "string",
        "inn": "string",
        "kbk": "string",
        "kio": "string",
        "kpp": "string",
        "purpose_of_payment": "string",
        "reason_for_trade": "string",
        "reference_information": "string",
        "russian_central_bank_account": "string",
        "swift_code": "string",
        "vo": "string",
        "account_id": "integer"
      }
    ],
    "beneficiary_id": "string",
    "created": "string",
    "aml_status": "string",
    "active": "string",
    "beneficiary_reference": "string",
  }
]

A successful request will return a 200 OK response with the response body containing a list of Beneficiary objects. In addition the total number of entries is available in the header field x-total-count.

Get a single beneficiary

GET /beneficiaries/$beneficiary_id?client_id=$client_id HTTP/1.1
Authorization: string

Get a single beneficiary by beneficiary ID

Path Parameters

Parameter	Description
`beneficiary_id` Required	The ID of the beneficiary

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "string",
  "email_addresses": [
    "string"
  ],
  "email_notification": "boolean",
  "address_line_1": "string",
  "street_name": "string",
  "building_number": "string",
  "floor": "string",
  "apartment_office_number": "string",
  "city": "string",
  "state_region": "string",
  "post_code": "string",
  "country_code": "string",
  "bank_accounts": [
    {
      "account_number": "string",
      "bank_address_line_1": "string",
      "bank_country_code": "string",
      "bank_currency_code": "string",
      "bank_identifier": "string",
      "bank_identifier_type": "string",
      "bank_name": "string",
      "correspondent_account": "string",
      "correspondent_swift_code": "string",
      "iban": "string",
      "inn": "string",
      "kbk": "string",
      "kio": "string",
      "kpp": "string",
      "purpose_of_payment": "string",
      "reason_for_trade": "string",
      "reference_information": "string",
      "russian_central_bank_account": "string",
      "swift_code": "string",
      "vo": "string",
      "account_id": "integer"
    }
  ],
  "beneficiary_id": "string",
  "created": "string",
  "aml_status": "string",
  "active": "string"
  "beneficiary_reference": "string",
}

A successful request will return a 200 OK response with the response body containing a Beneficiary object.

Update a beneficiary

PATCH /beneficiaries/$beneficiary_id?client_id=$client_id HTTP/1.1
Authorization: string

Content-Type: application/json

{
  "name": "string",
  "email_addresses": [
    "string"
  ],
  "email_notification": "boolean",
  "address_line_1": "string",
  "street_name": "string",
  "building_number": "string",
  "floor": "string",
  "apartment_office_number": "string",
  "city": "string",
  "state_region": "string",
  "post_code": "string",
  "country_code": "string",
  "bank_accounts": [
    {
      "account_number": "string",
      "bank_address_line_1": "string",
      "bank_country_code": "string",
      "bank_currency_code": "string",
      "bank_identifier": "string",
      "bank_identifier_type": "string",
      "bank_name": "string",
      "correspondent_account": "string",
      "correspondent_swift_code": "string",
      "iban": "string",
      "inn": "string",
      "kbk": "string",
      "kio": "string",
      "kpp": "string",
      "purpose_of_payment": "string",
      "reason_for_trade": "string",
      "reference_information": "string",
      "russian_central_bank_account": "string",
      "swift_code": "string",
      "vo": "string",
      "account_id": "integer"
    }
  ],
  "beneficiary_id": "string",
  "created": "string",
  "aml_status": "string",
  "active": "string",
  "beneficiary_reference": "string",
}

Update a single beneficiary by beneficiary ID, using a list of names and values.

We do not currently support PUT. This may be supported in a later release.

Request Headers

Header	Description
`Content-Type` Required	`application/json`

Path Parameters

Parameter	Description
`beneficiary_id` Required	The ID of the beneficiary you want to update

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Request Body

After a beneficiary has received a payment, the only fields available for modification are:

email_addresses
email_notification
beneficiary_reference

Fields

Name	Description
`name`	The name of the beneficiary
`email_addresses`	List of email addresses
`email_notification`	Whether the beneficiary should receive email notification of payments
`address_line_1`^*	The first address line of the beneficiary (deprecated)*
`street_name`^*	The street name of the beneficiary
`building_number`^*	The building number of the beneficiary
`floor`^*	The floor of the beneficiary
`apartment_office_number`^*	The apartment/office number of the beneficiary
`city`^*	The city of the beneficiary
`state_region`^*	The state/region of the beneficiary
`post_code`	The postcode of the beneficiary
`country_code`	The ISO 3166-1 alpha-2 code of the beneficiary's country
`account_number`	The account number of the bank account
`bank_address_line_1`	The first address line of the bank
`bank_country_code` Required	The ISO 3166-1 alpha-2 code of the bank's country
`bank_currency_code` Required	The ISO 4217 code of the bank account's currency
`bank_identifier`	The identifier of the bank
`bank_name`	Name of the bank account holder
`correspondent_account`	The account for the correspondent account of the bank
`correspondent_swift_code`	The SWIFT code for the correspondent account of the bank
`iban`	The IBAN of the bank account
`inn`	Unique Taxpayer Personal Identification Number for legal entities registered in Russia.
`kbk`	The KBK of the bank account
`kio`	Tax ID for foreign legal entities in Russia.
`kpp`	The KPP of the bank account
`purpose_of_payment`	The purpose of payment is mandatory when the beneficiary account has specific currency types. See the section PurposeOfPayment for the currencies and their acceptable values.
`reason_for_trade`	The reason for trade of the bank account
`reference_information`	The reference information which will be used as the default payment reference during payment initiation.
`beneficiary_reference`	Unique external reference ID submitted by the client for the beneficiary.
`russian_central_bank_account`	20-digit code for Russian banks.
`swift_code`	The SWIFT code of the bank account
`vo`	Code of currency transaction established by the Central Bank of Russia to describe the purpose of the payment.

* This field and the related rule becomes operational from October 2024. Further communication will follow over emails. Please note, it does not apply to Ebury Mass Payments customers in Production.

Response

HTTP/1.1 204 No Content

A successful request will return a 204 No Content response with an empty response body.

Delete a beneficiary

DELETE /beneficiaries/$beneficiary_id?client_id=$client_id HTTP/1.1
Authorization: string

Delete a single beneficiary by beneficiary ID

Path Parameters

Parameter	Description
`beneficiary_id` Required	The ID of the beneficiary you want to delete

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Response

HTTP/1.1 204 No Content

A successful request will return a 204 No Content response with an empty response body.

Beneficiary Models

BankAccount

{
  "account_number": "string",
  "bank_address_line_1": "string",
  "bank_country_code": "string",
  "bank_currency_code": "string",
  "bank_identifier": "string",
  "bank_identifier_type": "string",
  "bank_name": "string",
  "correspondent_account": "string",
  "correspondent_swift_code": "string",
  "iban": "string",
  "inn": "string",
  "kbk": "string",
  "kio": "string",
  "kpp": "string",
  "purpose_of_payment": "string",
  "reason_for_trade": "string",
  "reference_information": "string",
  "russian_central_bank_account": "string",
  "swift_code": "string",
  "vo": "string",
  "account_id": "string"
}

Bank account data. Refer to the Metadata API for valid field combinations.

Fields

Name	Description
`account_number`	The account number of the bank account
`bank_address_line_1`	The first address line of the bank
`bank_country_code` Required	The ISO 3166-1 alpha-2 code of the bank's country
`bank_currency_code` Required	The ISO 4217 code of the bank account's currency
`bank_identifier`	The identifier of the bank
`bank_identifier_type`	The identifier type of the bank
`bank_name`	Name of the bank account holder
`correspondent_account`	The account for the correspondent account of the bank
`correspondent_swift_code`	The SWIFT code for the correspondent account of the bank
`iban`	The IBAN of the bank account
`inn`	The INN of the bank account
`kbk`	The KBK of the bank account
`kio`	The KIO of the bank account
`kpp`	The KPP of the bank account
`purpose_of_payment`	The purpose of payment is mandatory when the beneficiary account has specific currency types. See the section PurposeOfPayment for the currencies and their acceptable values.
`reason_for_trade`	The reason for trade of the bank account
`reference_information`	The reference information which will be used as the default payment reference during payment initiation.
`russian_central_bank_account`	The Russian central account number of the bank account
`swift_code`	The SWIFT code of the bank account
`vo`	The VO of the bank account
`account_id` Required	The identifier of the bank account

BeneficiaryCoreData

{
  "name": "string",
  "email_addresses": [
    "string"
  ],
  "email_notification": "boolean",
  "address_line_1": "string",
  "street_name": "string",
  "building_number": "string",
  "floor": "string",
  "apartment_office_number": "string",
  "city": "string",
  "state_region": "string",
  "post_code": "string",
  "country_code": "string"
}

This model is a representation of a beneficiary's core data.

Fields

Name	Description
`name` Required	The name of the beneficiary
`email_addresses`	The list of beneficiary's email addresses
`email_notification` Required	Whether the beneficiary should receive email notification of payments
`address_line_1`	The first address line of the beneficiary
`street_name`^*	The street name of the beneficiary
`building_number`^*	The building number of the beneficiary
`floor`^*	The floor of the beneficiary
`apartment_office_number`^*	The apartment/office number of the beneficiary
`city`^* Required	The city of the beneficiary
`state_region`^*	The state/region of the beneficiary
`post_code`	The postcode of the beneficiary
`country_code` Required	The ISO 3166-1 alpha-2 code of the beneficiary's country

* This field and the related rule becomes operational from October 2024. Further communication will follow over emails. Please note, it does not apply to Ebury Mass Payments customers in Production.

Beneficiary

{
  "name": "string",
  "email_addresses": [
    "string"
  ],
  "email_notification": "boolean",
  "address_line_1": "string",
  "street_name": "string",
  "building_number": "string",
  "floor": "string",
  "apartment_office_number": "string",
  "city": "string",
  "state_region": "string",
  "post_code": "string",
  "country_code": "string",
  "bank_accounts": [
    {
      "account_number": "string",
      "bank_address_line_1": "string",
      "bank_country_code": "string",
      "bank_currency_code": "string",
      "bank_identifier": "string",
      "bank_identifier_type": "string",
      "bank_name": "string",
      "correspondent_account": "string",
      "correspondent_swift_code": "string",
      "iban": "string",
      "inn": "string",
      "kbk": "string",
      "kio": "string",
      "kpp": "string",
      "purpose_of_payment": "string",
      "reason_for_trade": "string",
      "reference_information": "string",
      "russian_central_bank_account": "string",
      "swift_code": "string",
      "vo": "string",
      "account_id": "integer"
    }
  ],
  "beneficiary_id": "string",
  "created": "string",
  "aml_status": "string",
  "active": "string",
  "beneficiary_reference": "string",
}

This model is a representation of a beneficiary.

Fields

Name	Description
`name` Always	The name of the beneficiary
`email_addresses`	The list of beneficiary's email addresses
`email_notification` Always	Whether the beneficiary should receive email notification of payments
`address_line_1`	The first address line of the beneficiary
`street_name`^*	The street name of the beneficiary
`building_number`^*	The building number of the beneficiary
`floor`^*	The floor of the beneficiary
`apartment_office_number`^*	The apartment/office number of the beneficiary
`city`^* Always	The city of the beneficiary
`state_region`^*	The state/region of the beneficiary
`post_code`	The postcode of the beneficiary
`country_code` Always	The ISO 3166-1 alpha-2 code of the beneficiary's country
`bank_accounts` Always	The list of beneficiary's bank accounts
`beneficiary_id` Always	The beneficiary ID
`created` Always	Creation date of the beneficiary
aml_status Always	AML status of the beneficiary
`active` Always	True if beneficiary is active, False otherwise
`beneficiary_reference`	Unique external reference ID submitted by the client for the beneficiary.

* This field and the related rule becomes operational from October 2024. Further communication will follow over emails. Please note, it does not apply to Ebury Mass Payments customers in Production.

AMLStatus

AML status of the Beneficiary

Values

Value	Description
`OK`	Beneficiary checks completed, ready to be paid
`Pending Review`	Reviewing beneficiary information
`Pending information`	Awaiting beneficiary information
`Blocked`	Client account blocked

PurposeOfPayment

Valid purpose of payment values.

When country is China, the following purpose of payment values are mandatory only for CNY currency

See values list

When country is United Arab Emirates, the following purpose of payment values are mandatory for all currencies

See values list

Getting Accounts

The Accounts API allows you to retrieve information for your accounts.

Retrieve a list of accounts

GET /accounts?client_id=$client_id HTTP/1.1
Authorization: string

Get all accounts for a given client.

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`currencies`	A comma-separated list of currency codes compliant to ISO 4217

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "account_id": "uuid",
    "account_subtype": "account_subtype",
    "account_type": "account_type",
    "account_details": [
      {
        "account_address": "account_address",
        "account_name": "account_name",
        "account_number": "account_number",
        "account_number_type": "account_number_type",
        "bank_identifier": "bank_identifier",
        "bank_identifier_type": "bank_identifier_type"
      },
      {
        "account_address": "account_address",
        "account_name": "account_name",
        "account_number": "account_number",
        "account_number_type": "account_number_type",
        "bank_identifier": "bank_identifier",
        "bank_identifier_type": "bank_identifier_type"
      }
    ],
    "currency": "currency",
    "status": "account_status"
  },
  {
    "account_id": "uuid",
    "account_subtype": "account_subtype",
    "account_type": "account_type",
    "account_details": [
      {
        "account_address": "account_address",
        "account_name": "account_name",
        "account_number": "account_number",
        "account_number_type": "account_number_type",
        "bank_identifier": "bank_identifier",
        "bank_identifier_type": "bank_identifier_type"
      },
      {
        "account_address": "account_address",
        "account_name": "account_name",
        "account_number": "account_number",
        "account_number_type": "account_number_type",
        "bank_identifier": "bank_identifier",
        "bank_identifier_type": "bank_identifier_type"
      }
    ],
    "currency": "currency",
    "status": "account_status"
  }
]

A successful request will return a 200 OK response with the response body containing a list of AccountDetails objects.

Retrieve an account

GET /accounts/$account_id?client_id=$client_id HTTP/1.1
Authorization: string

Retrieve a single account by account ID.

Path Parameters

Parameter	Description
`account_id` Required	The UUID of the account

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "account_id": "uuid",
    "account_subtype": "account_subtype",
    "account_type": "account_type",
    "account_details": [
        {
            "account_address": "account_address",
            "account_name": "account_name",
            "account_number": "account_number",
            "account_number_type": "account_number_type",
            "bank_identifier": "bank_identifier",
            "bank_identifier_type": "bank_identifier_type"
        },
        {
            "account_address": "account_address",
            "account_name": "account_name",
            "account_number": "account_number",
            "account_number_type": "account_number_type",
            "bank_identifier": "bank_identifier",
            "bank_identifier_type": "bank_identifier_type"
        }
    ],
    "currency": "currency",
    "status": "account_status"
}

A successful request will return a 200 OK response with the response body containing an AccountData object.

Account Models

These models are returned by the get all accounts and get an account endpoints.

AccountData

[
  {
    "account_id": "uuid",
    "account_subtype": "account_subtype",
    "account_type": "account_type",
    "account_details": [
      {
        "account_address": "account_address",
        "account_name": "account_name",
        "account_number": "account_number",
        "account_number_type": "account_number_type",
        "bank_identifier": "bank_identifier",
        "bank_identifier_type": "bank_identifier_type"
      },
      {
        "account_address": "account_address",
        "account_name": "account_name",
        "account_number": "account_number",
        "account_number_type": "account_number_type",
        "bank_identifier": "bank_identifier",
        "bank_identifier_type": "bank_identifier_type"
      }
    ],
    "currency": "currency",
    "status": "account_status"
  },
  {
    "account_id": "uuid",
    "account_subtype": "account_subtype",
    "account_type": "account_type",
    "account_details": [
      {
        "account_address": "account_address",
        "account_name": "account_name",
        "account_number": "account_number",
        "account_number_type": "account_number_type",
        "bank_identifier": "bank_identifier",
        "bank_identifier_type": "bank_identifier_type"
      },
      {
        "account_address": "account_address",
        "account_name": "account_name",
        "account_number": "account_number",
        "account_number_type": "account_number_type",
        "bank_identifier": "bank_identifier",
        "bank_identifier_type": "bank_identifier_type"
      }
    ],
    "currency": "currency",
    "status": "account_status"
  }
]

This model is a representation of an account within Ebury.

Fields

Name	Description
`currency` Always	Identification of the currency in which the account is held
`account_details` Always	The list of `AccountDetail`s for this `currency`
`status` Always	The `AccountStatus` of the account
`account_id` Always	The UUID of the account
`account_type` Always	The `AccountType` of the account
`account_subtype` Always	The `AccountSubType` of the account

AccountDetails

{
    "account_id": "uuid",
    "account_subtype": "account_subtype",
    "account_type": "account_type",
    "account_details": [
        {
            "account_address": "account_address",
            "account_name": "account_name",
            "account_number": "account_number",
            "account_number_type": "account_number_type",
            "bank_identifier": "bank_identifier",
            "bank_identifier_type": "bank_identifier_type"
        },
        {
            "account_address": "account_address",
            "account_name": "account_name",
            "account_number": "account_number",
            "account_number_type": "account_number_type",
            "bank_identifier": "bank_identifier",
            "bank_identifier_type": "bank_identifier_type"
        }
    ],
    "currency": "currency",
    "status": "account_status"
}

This model is a representation of account data associated with an Account.

Fields

Name	Description
`account_address` Always	The address of the account
`account_name` Always	The name or names of the account owner(s) represented at an account level
`account_number` Always	The number of the account
`account_number_type` Always	The `AccountNumberType` of the account number
`bank_identifier` Always	The identifier of the bank
`bank_identifier_type` Always	The `BankIdentifierType` of the bank identifier

AccountStatus

This is an enumeration of the statuses of an account.

Values

Value	Description
`Enabled`	Account is enabled.
`Disabled`	Account is disabled.

AccountType

This is an enumeration of the types of an account.

Values

Value	Description
`Personal`	Individual account.
`Business`	Corporate account.

AccountSubType

This is an enumeration of sub types of an account (product family group).

Values

Value	Description
`EMoney`

AccountNumberType

This is an enumeration of number types of an account.

Values

Value	Description
`IBAN`
`BBAN`

BankIdentifierType

This is an enumeration of bank identifier types, to comply with ISO20022 codes related to Clearing System Identification, with the addition of SWBIC for swift international payments.

Values

Value	Description
`SWBIC`	Used for swift international payments.
other	Please refer to `ExternalClearingSystemIdentification1Code` inside Clearing System Identification of ISO20022.

Getting Account Details

Generate New Collection Account (Coming soon)

API clients will be able to call the POST Account details endpoint to request a new client named collection account from Ebury using the API.

POST /account-details?client_id=$client_id HTTP/1.1
Authorization: string

{
    “alias”: “string”,
    "country": "string",
    "currency": “string”
}

Request Headers

Query Parameters

Name	Field Type	Location	Max Length	Mandatory	Additional Info
`client_id`	`string`	`query`	`32`	`Y`	The client identifier you are requesting this account for.

Request Body

Name	Field Type	Location	Max Length	Mandatory	Additional Info
`alias`	`string`	`body`	`50`	`N`	User-friendly alias for the account. Only present (and mandatory) for dedicated accounts.
`country`	`string`	`body`	`2`	`Y`	ISO 3166-1 Alpha-2 code.
`currency`	`string`	`body`	`3`	`Y`	ISO 4217 Alpha-3 code.

Response

A successful request will return a 200 OK response with the response body containing a list of AccountDetails objects. In addition, the total number of entries retrieved is available in header field x-total-count.

Getting Account Details Metadata

Retrieve the list of currencies and countries where a customer can open a virtual account. Bear in mind that not all accounts can be opened automatically from the API, in certain cases, it is required to contact the Ebury relationship manager.

Request Headers

GET /account-details/metadata?client_id=$client_id HTTP/1.1
Authorization: string

[
    {
    “auto_create”: “boolean”,
    "country": "string",
    "currency": “string”
    },
]

Query Parameters

Name	Field Type	Location	Max Length	Accepted Values	Mandatory	Additional Info
`client_id`	`string`	`query`	`32`		`Y`
`country`	`string`	`query`	`2`	`Regex: [A-Z]{2}`	`N`	ISO 3166-1 Alpha-2 code.
`currency`	`string`	`query`	`3`	`Regex: [A-Z]{3}`	`N`	ISO 4217 Alpha-3 code.
`page`	`integer`	`query`		`>=1`	`N`
`page_size`	`integer`	`query`		`>=1`	`N`

Response

[
    {
        "auto_create": false,
        "country": "BE",
        "currency": "GBP"
    },
    {
        "auto_create": false,
        "country": "GB",
        "currency": "EUR"
    },
    {
        "auto_create": false,
        "country": "GB",
        "currency": "GBP"
    },
    {
        "auto_create": false,
        "country": "GB",
        "currency": "USD"
    },
    {
        "auto_create": false,
        "country": "NL",
        "currency": "AED"
    }
]

A successful request will return a 200 OK response with a response body consisting of an array of objects with the following fields:

Name	Field Type	Location	Max Length	Additional Info
`content-type`	`application/json`	`header`
`x-total-count`	`integer`	`header`		Total number of entries returned.
`auto-create`	`boolean`	`body`		If this is set to “false”, it means that the client is not able to automatically create an account in that currency and country.
`country`	`string`	`body`	`2`	An ISO 3166-1 Alpha-2 code will be returned.
`currency`	`string`	`body`	`3`	An ISO 4217 Alpha-3 code will be returned.

Mark an account as primary

Mark the account as primary (default) for its holder and currency. Only dedicated accounts can be set as primary, trying this operation for a pooled account will return an error.

Request Headers

POST /account-details/$account_details_id/make-default?client_id=$client_id HTTP/1.1
Authorization: string

Query Parameters

Name	Field Type	Location	Max Length	Accepted Values	Mandatory	Additional Info
`client_id`	`string`	`query`	`32`		`Y`	ID of the client that owns the account details
`account_details_id`	`string`	`path`	`36`	`uuid`	`Y`	Unique ID of the account

Response

A successful request will return a 204 No Content response.

Retrieve Account Details

Retrieve the account details for a given client, possibly filtered by some criteria.

Request Headers

GET /account-details?client_id=$client_id HTTP/1.1
Authorization: string

Query Parameters

Name	Field Type	Location	Max Length	Accepted Values	Mandatory	Additional Info
`client_id`	`string`	`query`	`32`		`Y`	ID of the client that owns the account details
`account_details_type`	`string`	`query`		`-dedicated` `-pooled`	`N`	Filter by account details type
`account_id`	`string`	`query`	`36`	`uuid`	`N`	Filter by the unique ID of the account
`country`	`string`	`query`	`2`	`Regex: [A-Z]{2}`	`N`	Filter by the country of the account (ISO Code 2)
`currency`	`string`	`query`	`3`	`Regex: [A-Z]{3}`	`N`	Filter by the currency of the account (ISO Code 3)
`alias`	`string`	`query`	`50`		`N`	Filter by the user-friendly alias of the account. Only dedicated accounts can be filtered by alias.
`page`	`integer`	`query`		`>=1`	`N`	Default value is 1.
`page_size`	`integer`	`query`		`>=1`	`N`	Default value is 50.

Response

Update Account Details

Update or change the alias for a given account for a given client. Only dedicated accounts can be patched, trying to patch a pooled account will return an error.

Request Headers

PATCH /account-details/$account_details_id?client_id=$client_id HTTP/1.1
Authorization: string
Content-Type: application/json

{
    "alias": "NL EUR Account"
}

Query Parameters

Name	Field Type	Location	Max Length	Accepted Values	Mandatory	Additional Info
`client_id`	`string`	`query`	`32`		`Y`	ID of the client that owns the account details
`account_details_id`	`string`	`path`	`36`	`uuid`	`Y`	Unique ID of the account

Request Body

Name	Field Type	Location	Max Length	Mandatory
`alias`	`string`	`body`	`50`	`Y`

Response

Account Details Model

These models are returned by Retrieving Account Details, Generate New Collection Account and Update Account Details endpoints.

AccountDetails Data

[
    {
        "account_details_id": "42101706-b568-410f-88f5-43f39869304f",
        "account_details_type": "dedicated",
        "account_holder_address": "",
        "account_holder_name": "Implementation Account",
        "account_id": "5b40a865-72ed-5159-96ba-8d4389d0051e",
        "alias": "NL EUR Account",
        "country": "NL",
        "created": "2020-12-10 13:01:13.857898",
        "currency": "EUR",
        "domestic": null,
        "financial_institution_address": "Claude Debussylaan 26\n1028 MD, Amsterdam",
        "financial_institution_name": "EBURY PARTNERS NETHERLANDS",
        "international": {
            "account_number": "NL55RABO3717231707",
            "account_number_type": "IBAN",
            "bank_identifier": "EBURNL21",
            "bank_identifier_type": "SWBIC"
        },
        "modified": "2020-12-10 13:31:46.929423",
        "primary": true,
        "status": "confirmed"
    },
    {
        "account_details_id": "c5733e6d-9de8-46ce-e731-07d6fa4093b6",
        "account_details_type": "pooled",
        "account_holder_address": "100 Victoria Street London SW1E 5JL",
        "account_holder_name": "Ebury Partners UK Limited",
        "account_id": null,
        "country": "GB",
        "currency": "NZD",
        "domestic": {
            "account_number": "4006003",
            "account_number_type": "BBAN",
            "bank_identifier": "312840",
            "bank_identifier_type": "NZNCC"
        },
        "financial_institution_address": "Citibank Centre 23 Customs Street East\n1140\nAUCKLAND",
        "financial_institution_name": "Citibank NA New Zealand Branch",
        "international": {
            "account_number": "4006003",
            "account_number_type": "BBAN",
            "bank_identifier": "CITINZ2X",
            "bank_identifier_type": "SWBIC"
        },
        "status": "confirmed"
    }
]

This model is a representation of account details within Ebury.

Fields

Name	Description
`account_id` Always	The UUID of the account.
`account_details_id` Always	(uuid) Unique ID of the account details
`account_details_type` Always	The AccountDetailsType
`alias`	User-friendly alias for the account. Only available (and mandatory) on dedicated accounts
`account_holder_address` Always	The address of the account holder
`account_holder_name` Always	The name of the account holder
`country` Always	The country of the account-details. An ISO 3166-1 Alpha-2 code will be returned
`currency` Always	Identification of the currency in which the account is held. An ISO 3166-1 Alpha-2 code will be returned
`domestic`	Domestic information of the account. It can be null. See the list of Domestic AccountDetails
`international`	International information of the account. It can be null. See the list of International AccountDetails
`financial_institution_name`	The name of the FI
`financial_institution_address`	The address of the FI
`modified`	In YYYY-MM-DD hh:mm:ss.SSS format. Datetime of last modification (for dedicated accounts only)
`primary`	If "true" the account is marked as default (for dedicated accounts only)
`status` Always	The AccountDetailsStatus

AccountDetails Type

This is an enumeration of account-details types.

VALUES

Value	Description
`Dedicated`	The account is dedicated
`Pooled`	The account is pooled

Domestic AccountDetails

This model is a representation of domestic account-details associated with an Account.

FIELDS

Name	Description
`domestic.account_number`	The number of the account
`domestic.account_number_type`	Account Number Type
`domestic.bank_identifier`	The identifier of the bank.
`domestic.bank_identifier_type`	Bank Identifier Type

International AccountDetails

This model is a representation of international account-details associated with an Account.

FIELDS

Name	Description
`international.account_number`	The number of the account
`international.account_number_type`	Account Number Type
`international.bank_identifier`	The identifier of the bank.
`international.bank_identifier_type`	Bank Identifier Type

AccountDetailsStatus

This is an enumeration of the statuses of an account.

VALUES

Value	Description
`Pending`	The account is pending to be created
`Confirmed`	The account creation is created
`Failed`	The account creation has failed

Getting Balances

The Balances API allows you to retrieve the balances for your accounts.

Get balances for all accounts

GET /balances?client_id=$client_id HTTP/1.1
Authorization: string

Get all balances for all accounts for a given client.

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`currencies`	A comma-separated list of currency codes compliant to ISO 4217
`balance_types`	A list of available balance types. One of `BalanceTypes`. Default is `InterimAvailable`.

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "account_id": "5358dae1-269e-c21e-952b-b8b8d597dcce",
    "amount": {
      "amount": "0.0000",
      "currency": "USD"
    },
    "credit_debit_indicator": "Credit",
    "datetime": "2019-10-24T22:37:22.547",
    "type": "InterimAvailable"
  },
  {
    "account_id": "c18a42df-6652-d462-351b-0485a6d6bc16",
    "amount": {
      "amount": "50112.8500",
      "currency": "EUR"
    },
    "credit_debit_indicator": "Credit",
    "datetime": "2019-10-24T22:37:22.547",
    "type": "InterimAvailable"
  }
]

A successful request will return a 200 OK response with the response body containing a list of BalanceData objects.

Get balances for a single account

GET /accounts/$account_id/balances?client_id=$client_id HTTP/1.1
Authorization: string

Retrieve all balances for a single account by account ID.

Path Parameters

Parameter	Description
`account_id`	The UUID of the account

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`balance_types`	A list of available balance types. One of `BalanceTypes`. Default is `InterimAvailable`.

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "account_id": "5358dae1-269e-c21e-952b-b8b8d597dcce",
    "amount": {
      "amount": "150.0000",
      "currency": "USD"
    },
    "credit_debit_indicator": "Credit",
    "datetime": "2019-10-24T22:37:22.547",
    "type": "InterimAvailable"
  }
]

A successful request will return a 200 OK response with the response body containing a list of BalanceData objects.

Balance Models

These models are returned by the get all balances and get an account balances endpoints.

BalanceData

  {
    "account_id": "5358dae1-269e-c21e-952b-b8b8d597dcce",
    "amount": {
      "amount": "150.0000",
      "currency": "USD"
    },
    "credit_debit_indicator": "Credit",
    "datetime": "2019-10-24T22:37:22.547",
    "type": "InterimAvailable"
  }

This model is a representation of a single balance for an account within Ebury.

Fields

Name	Description
`account_id` Always	The UUID of the account
`amount` Always	Object of `Amount`
`credit_debit_indicator` Always	One of `CreditDebitIndicator`
`datetime` Always	Date and time
`type` Always	Type of the balance. One of `BalanceType`

Amount

{
  "amount": "150.0000",
  "currency": "USD"
}

This model is a representation of a balance/transaction amount.

Fields

Name	Description
`amount` Always	The balance/transaction amount
`currency` Always	The ISO 4217 code of the balance currency

BalanceType

This is an enumeration of the balance types of an account.

Values

Value	Description
`InterimAvailable`	Available balance calculated in the course of the account servicer's business day.
`RequiredFunds`	Funds required on account taking in mind future payments, trades and fees.

CreditDebitIndicator

Whether the balance/transaction amount is credit or debit

Values

Value	Description
`Debit`	The amount is debit
`Credit`	The amount is credit

Getting Currencies

The Currencies API allows you to retrieve the information about currencies of the client.

Get currencies

GET /currencies?client_id=$client_id HTTP/1.1
Authorization: string

Get all currencies for a given client.

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`trade_type`	Type of trade. One of `TradeTypes`. Default value is `spot`.
`currency`	A comma-separated list of currency codes compliant to ISO 4217

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "currency": "USD",
        "available_for_trading": true,
        "credit_limit": "-901220.0000",
        "default": false,
        "holidays": [
            "2017-06-08T00:00:00+05"
        ],
        "currency_limit": "734408.5000",
        "decimals": 2,
        "cutoff": {
            "days": 0,
            "time":  "23:00:00+00"
        },
        "buy_allowed": true,
        "sell_allowed": true
    },
    {
        "currency": "GBP",
        "available_for_trading": true,
        "credit_limit": "3998760.0000",
        "default": true,
        "holidays": [
            "2017-06-09T00:00:00+05",
            "2017-06-08T00:00:00+05"
        ],
        "currency_limit": "500000.0000",
        "decimals": 2,
        "cutoff": {
            "days": 0,
            "time":  "23:00:00+00"
        },
        "buy_allowed": true,
        "sell_allowed": true    
    }
]

A successful request will return a 200 OK response with the response body containing a list of CurrencyInfo objects.

Currency Models

TradeType

This is an enumeration of the balance types of an account.

Values

Value	Description
`spot`	Spot trade
`forward`	Forward trade

CurrencyInfo

    {
        "currency": "USD",
        "available_for_trading": true,
        "credit_limit": "-901220.0000",
        "default": false,
        "holidays": [
            "2017-06-08T00:00:00+05"
        ],
        "currency_limit": "734408.5000",
        "decimals": 2,
        "cutoff": {
            "days": 0,
            "time":  "23:00:00+00"
        },
        "buy_allowed": true,
        "sell_allowed": true
    }

This model is a representation of a single currency of an Ebury client.

Fields

Name	Description
`currency` Always	Currency symbol
`available_for_trading` Always	Is this currency available to trade
`credit_limit` Always	Limit of the credit
`default` Always	Is this default currency of the client
`holidays` Always	List of holidays in a format ISO-8601
`currency_limit` Always	Limit of the currency
`decimals` Always	Decimal settings of the client for the currency
`cutoff` Always	Object of Cutoff
`buy_allowed` Always	Is client allowed to buy this currency
`sell_allowed` Always	Is client allowed to sell this currency

Cutoff

{
  "days": 0,
  "time": "23:00:00+00"
}

This model is a representation of a cutoff for a currency.

Fields

Name	Description
`days` Always	Cutoff days for the currency
`time` Always	Cutoff time for the currency. Includes TZ data in ISO format

Getting Transactions

The Transactions API allows you to retrieve the transactions for your accounts.

Get transactions for all accounts

GET /transactions?client_id=$client_id HTTP/1.1
Authorization: string

Get all transactions for all accounts for a given client.

Transactions can be filtered by value date and time. If no value date and time filter is set, it will return the latest 50 transactions.

Retrieving transactions with value date and time before June 1st, 2019 is not supported yet.

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`credit_debit_indicator`	Only return transactions specified by this parameter. Accepted values are 'credit' and 'debit'.
`currencies`	A comma-separated list of currency codes compliant to ISO 4217
`from_value_datetime`	Only return transactions with value date and time after this UTC date and time. YYYY-MM-DDThh:mm format
`to_value_datetime`	Only return transactions with value date and time before this UTC date and time. YYYY-MM-DDThh:mm format
`page`	The desired page number for pagination. Default value is `1`.
`page_size`	The number of items per page for pagination. Default value is `50`.
`transaction_type`	Only return transactions of the specified `TransactionType`.

Response

HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1

[
  {
    "account_id": "c18a42df-6652-d462-351b-0485a6d6bc16",
    "additional_transaction_information": "EURGBP 0.876804 - other",
    "amount": {
        "amount": "100.00",
        "currency": "EUR"
    },
    "balance": {
        "amount": {
            "amount": "50212.85",
            "currency": "EUR"
        },
        "credit_debit_indicator": "Credit",
        "type": "InterimAvailable"
    },
    "booking_datetime": "2019-11-11T20:37:30.598",
    "client_id": "EBPCLI285330",
    "credit_debit_indicator": "Credit",
    "creditor_account": {
        "account_name": "EBURY OFFICE ACC CHF",
        "account_number": "",
        "bank_identifier": "",
        "bank_identifier_code": "",
        "iban": "GB78BARC12345678901234",
        "swift": ""
    },
    "creditor_name": "Jorge Chapa",
    "debtor_account": {
        "account_name": "Cool Account",
        "account_number": "1234567890",
        "bank_identifier": "123456",
        "bank_identifier_code": "",
        "iban": "",
        "swift": "RACZHUH1123"
    },
    "debtor_name": "Jorge Corp",
    "status": "Booked",
    "transaction_id": "3ae5b450-1e1a-b116-1fde-3cb4f0353e16",
    "transaction_information": "Bought EUR EBPOTR002772",
    "transaction_reference": "EBPOTR002772",
    "transaction_type": "credit",
    "value_datetime": "2019-11-11T20:37:30.598"
  }
]

A successful request will return a 200 OK response with the response body containing a list of TransactionData objects. In addition the total number of entries retrieved is available in header field x-total-count.

Get transactions for a single account

GET /accounts/$account_id/transactions?client_id=$client_id HTTP/1.1
Authorization: string

Retrieve all transactions for a single account by account ID.

Transactions can be filtered by value date and time. If no value date and time filter is set, it will return the latest 50 transactions.

Retrieving transaction booked before June 1st, 2019 is not supported yet.

Path Parameters

Parameter	Description
`account_id` Required	The UUID of the account

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`credit_debit_indicator`	Only return transactions specified by this parameter. Accepted values are 'credit' and 'debit'.
`from_value_datetime`	Only return transactions with value date and time after this UTC date and time. YYYY-MM-DDThh:mm format
`to_value_datetime`	Only return transactions with value date and time before this UTC date and time. YYYY-MM-DDThh:mm format
`page`	The desired page number for pagination. Default value is `1`.
`page_size`	The number of items per page for pagination. Default value is `50`.
`transaction_type`	Only return transactions of the specified `TransactionType`.

Response

HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1

[
  {
    "account_id": "c18a42df-6652-d462-351b-0485a6d6bc16",
    "additional_transaction_information": "EURGBP 0.876804 - other",
    "amount": {
        "amount": "100.00",
        "currency": "EUR"
    },
    "balance": {
        "amount": {
            "amount": "50212.85",
            "currency": "EUR"
        },
        "credit_debit_indicator": "Credit",
        "type": "InterimAvailable"
    },
    "booking_datetime": "2019-11-11T20:37:30.598",
    "client_id": "EBPCLI285330",
    "credit_debit_indicator": "Credit",
    "creditor_account": {
        "account_name": "EBURY OFFICE ACC CHF",
        "account_number": "",
        "bank_identifier": "",
        "bank_identifier_code": "",
        "iban": "GB78BARC12345678901234",
        "swift": ""
    },
    "creditor_name": "Jorge Chapa",
    "debtor_account": {
        "account_name": "Cool Account",
        "account_number": "1234567890",
        "bank_identifier": "123456",
        "bank_identifier_code": "",
        "iban": "",
        "swift": "RACZHUH1123"
    },
    "debtor_name": "Jorge Corp",
    "status": "Booked",
    "transaction_id": "3ae5b450-1e1a-b116-1fde-3cb4f0353e16",
    "transaction_information": "Bought EUR EBPOTR002772",
    "transaction_reference": "EBPOTR002772",
    "transaction_type": "credit",
    "value_datetime": "2019-11-11T20:37:30.598"
  }
]

Get a single transaction

GET /accounts/$account_id/transactions/$transaction_id?client_id=$client_id HTTP/1.1
Authorization: string
X-Contact-ID: string

Retrieve a single transaction for an account by account ID and transaction ID.

Path Parameters

Parameter	Description
`account_id` Required	The UUID of the account
`transaction_id` Required	The UUID of the transaction

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Response

HTTP/1.1 200 OK
Content-Type: application/json


{
  "account_id": "c18a42df-6652-d462-351b-0485a6d6bc16",
  "additional_transaction_information": "EURGBP 0.876804 - other",
  "amount": {
      "amount": "100.00",
      "currency": "EUR"
  },
  "balance": {
      "amount": {
          "amount": "50212.85",
          "currency": "EUR"
      },
      "credit_debit_indicator": "Credit",
      "type": "InterimAvailable"
  },
  "booking_datetime": "2019-11-11T20:37:30.598",
  "client_id": "EBPCLI285330",
  "credit_debit_indicator": "Credit",
  "creditor_account": {
      "account_name": "EBURY OFFICE ACC CHF",
      "account_number": "",
      "bank_identifier": "",
      "bank_identifier_code": "",
      "iban": "GB78BARC12345678901234",
      "swift": ""
  },
  "creditor_name": "Jorge Chapa",
  "debtor_account": {
      "account_name": "Cool Account",
      "account_number": "1234567890",
      "bank_identifier": "123456",
      "bank_identifier_code": "",
      "iban": "",
      "swift": "RACZHUH1123"
  },
  "debtor_name": "Jorge Corp",
  "status": "Booked",
  "transaction_id": "3ae5b450-1e1a-b116-1fde-3cb4f0353e16",
  "transaction_information": "Bought EUR EBPOTR002772",
  "transaction_reference": "EBPOTR002772",
  "transaction_type": "credit",
  "value_datetime": "2019-11-11T20:37:30.598"
}

A successful request will return a 200 OK response with the response body containing a TransactionData object.

Transaction Models

These models are returned by the get all transactions and get an account transactions endpoints.

TransactionData

  {
    "account_id": "c18a42df-6652-d462-351b-0485a6d6bc16",
    "additional_transaction_information": "EURGBP 0.876804 - other",
    "amount": {
        "amount": "100.00",
        "currency": "EUR"
    },
    "balance": {
        "amount": {
            "amount": "50212.85",
            "currency": "EUR"
        },
        "credit_debit_indicator": "Credit",
        "type": "InterimAvailable",
    },
    "booking_datetime": "2019-11-11T20:37:30.598",
    "client_id": "EBPCLI285330",
    "credit_debit_indicator": "Credit",
        "creditor_account": {
        "account_name": "EBURY OFFICE ACC CHF",
        "account_number": "",
        "bank_identifier": "",
        "bank_identifier_code": "",
        "iban": "GB78BARC12345678901234",
        "swift": ""
    },
    "creditor_name": "Jorge Chapa",
    "debtor_account": {
        "account_name": "Cool Account",
        "account_number": "1234567890",
        "bank_identifier": "123456",
        "bank_identifier_code": "",
        "iban": "",
        "swift": "RACZHUH1123"
    },
    "debtor_name": "Jorge Corp",
    "status": "Booked",
    "transaction_id": "3ae5b450-1e1a-b116-1fde-3cb4f0353e16",
    "transaction_information": "Bought EUR EBPOTR002772",
    "transaction_reference": "EBPOTR002772",
    "transaction_type": "credit",
    "value_datetime": "2019-11-11T20:37:30.598"
  }

This model is a representation of a single transaction for an account within Ebury.

Fields

Name	Description
`account_id` Always	The UUID of the account
`additional_transaction_information` Always	Additional information for the transaction
`amount` Always	The `Amount` of the transaction
`balance` Always	The `Balance` of the transaction
`booking_datetime` Always	Date and time (UTC) when the transaction was booked
`client_id` Always	Identifier of the client
`credit_debit_indicator` Always	One of `CreditDebitIndicator`
`creditor_account` Always	The `Bank Account` information of the creditor
`creditor_name` Always	Name of the creditor
`debtor_account` Always	The `Bank Account` information of the debtor
`debtor_name` Always	Name of the debtor
`status` Always	One of `TransactionStatus`
`transaction_id` Always	The UUID of the transaction
`transaction_information` Always	Basic information for the transaction
`transaction_reference` Always	Reference for the transaction
`transaction_type` Always	The `TransactionType` of the transaction
`value_datetime` Always	Value date and time (UTC) of the transaction

TransactionBalance

{
    "amount": {
        "amount": "50212.85",
        "currency": "EUR"
    },
    "credit_debit_indicator": "Credit",
    "type": "InterimAvailable"
}

This model is a representation of the balance of the account (rounded to the currency decimal places) when the transaction happens.

Fields

Name	Description
`amount` Always	The `Amount` of the transaction
`credit_debit_indicator` Always	One of `CreditDebitIndicator`
`type` Always	Type of the balance. One of `BalanceType`

TransactionStatus

This is an enumeration of the transaction status types

Values

Value	Description
`Booked`	Booked

TransactionType

This is an enumeration of the transaction types

Values

Value	Description
`credit`	Record of any activity that generates a positive(credit) transaction on the account.
`debit`	Record of any activity that generates a negative(debit) transaction on the account (debit from the customer account).
`incoming`	Record of the incoming funds from an external source (credit into customer account from third parties, other clients, client’s own accounts at other banks etc.,). incoming as a type exclusively covers a subset of transactions which are originally of the type credit.
`margin`	Record of the deposits, refunds related to forward trades.
`payment_returned`	Record created when funds can’t be credited to the beneficiary and the counterparty returned the funds to the customer.

CreditorDebtorAccount

{
    "account_name": "Cool Account",
    "account_number": "1234567890",
    "bank_identifier": "123456",
    "bank_identifier_code": "",
    "iban": "",
    "swift": "RACZHUH1123"
}

This model is a representation of the bank account information for the creditor/debtor of a transaction

Fields

Name	Description
`account_name` Always	The name of the account's owner
`account_number` Always	Account number
`bank_identifier` Always	Account bank identifier
`bank_identifier_code` Always	Account bank identifier code (UK sort code, US ABA/FedWire, etc.)
`iban` Always	Account IBAN
`swift` Always	Account SWIFT code

Getting Statements

The Statements API allows you to create and retrieve the statement for an account in pdf, csv or mt940 formats.

Create statement for an account

POST /accounts/$account_id/statements/file?client_id=$client_id HTTP/1.1
Authorization: string
Content-Type: application/json

{
    "from_value_datetime": "2019-12-01T00:00:00",
    "to_value_datetime": "2019-12-01T23:59:59"
}

Generate a statement asynchronously in PDF, CSV or MT940 format for a given account.

It is not possible to generate statements for periods longer than 31 days.

In order to retrieve the generated statement go to Retrieve a statement for an account

Path Parameters

Parameter	Description
`account_id` Required	The UUID of the account

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`format`	The `File Format` in which the statement will be generated. Default value is `pdf`.

Request Body

Fields

Name	Description
`from_value_datetime` Required	Only return transactions after this value date (included). It is not possible to generate statements for periods longer than 31 days. It used to take into account the time, but it does not any longer: it defaults to the start of the date. YYYY-MM-DDThh:mm format
`to_value_datetime`	Only return transactions before this value date (included). It is not possible to generate statements for periods longer than 31 days. It used to take into account the time, but it does not any longer: it defaults to the end of the date. YYYY-MM-DDThh:mm format. Only required for `CSV` and `MT940` formats. For `PDF` format defaults to the current date and time

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "url": "/accounts/f51303e6-a591-6331-7a63-0a39794c712a/statements/c01d8acb-ec28-7a94-169f-fff7bf092fab/file"
}

A successful request will return a 202 ACCEPTED response with the response body containing a StatementFileData object.

StatementFileData

  {
    "url": "/accounts/f51303e6-a591-6331-7a63-0a39794c712a/statements/c01d8acb-ec28-7a94-169f-fff7bf092fab/file"
  }

This model containts the url that is needed in order to retrieve the statement once its processing has finished.

Fields

Name	Description
`url` Always	The url needed to retrieve the statement. It contains two UUID values, the first one (from the left) is the account id and the second one is the statement id.

Retrieve a statement for an account

GET /accounts/$account_id/statements/$statement_id/file?client_id=$client_id HTTP/1.1
Authorization: string

Get a previously generated statement.

For MT940 statements, the result will be a zip file with one MT940 file for each day in the given period. If there are no transactions for a given day, an MT940 will be generated anyway for that day with the account information.

All the date and time values for the CSV and PDF statements will be localized in the client's contact time zone.

Path Parameters

Parameter	Description
`account_id`	The UUID of the account
`statement_id`	The UUID of the statement

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Response

HTTP/1.1 202 OK
Content-Type: application/json

{
  "status": "Pending"
}

A successful request will return either a 200 OK with the statement file as an attachment if the statement processing has finished or a 202 ACCEPTED and contain a StatementFileStatus object with the status of the statement if it is not ready yet.

Statements Models

These models are used by the create and get statements endpoints.

StatementSupportedTypes

This is an enumeration of the supported formats for a statement

Values

Value	Description
`pdf`	Generate a single statement in pdf format.
`csv`	Generate a single statement in csv format.
`mt940`	Generate multiple statements, one for each day in the period, in mt940 format. The result will be a zip file with all the mt940 statements.

StatementFileStatus

  {
    "status": "Pending"
  }

This model is a representation of the current status of statement.

Fields

Name	Description
`status` Always	The `StatementStatus` for the statement.

StatementStatus

This is an enumeration of possible status in which a statement can be.

Values

Value	Description
`Pending`	The statement has not been processed yet.
`Failed`	The statement processing failed.

Making Payments

The Payments API allows you make payments to a known beneficiary with or without a trade associated with it.

In general, you can make payments in one of the two ways:

Pay immediately: When a payment instruction is sent the payment will be made immediately if the beneficiary has been validated and funds are available, or as soon as validation and funding has been completed. With this set-up only the GET and POST HTTP methods are available. Should you need to stop or return a payment manual intervention will be required by the Operations team;
Pay when authorised: Once a payment instruction has been sent an additional authorisation step is required to execute the payment: This step can either approve or reject the payment. With this set-up the PATCH and DELETE HTTP methods are available, to approve and reject the payment respectively. Note that if authorisation is required you require at least two contacts registered on your Ebury account as authorisation cannot be completed by one contact.

The choice of immediate payment or when authorised needs to be made when your Ebury account is created; you should consider carefully which set-up best fits your needs.

Create one or more new payments

POST /payments?client_id=$client_id HTTP/1.1
Authorization: string

Content-Type: application/json

{
    "trade_id": "string",
    "async": "boolean",
    "purpose_of_payment": "string",
    "payments": [
        {
            "beneficiary_id": "string",
            "account_id": "string",
            "amount": "number",
            "email_beneficiary": "boolean",
            "payment_date": "string",
            "reference": "string"
        }
    ]
}

Create one or more payments with a beneficiary_id (mandatory only for trade-based payment and not needed for independent payments), account_id and with or without an existing trade_id. Payment processing can be made asynchronous by setting the async flag in the request body. Please note, payments can be submitted without a trade_id and they are referred to as independent payments. For these payments, there won’t be any currency conversion as the payment will be funded from the corresponding account’s balance. Therefore, these payments are not preceded by a conversion (quote and trade).

Request Headers

Header	Description
`Content-Type` Required	`application/json`

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`include_errors` Optional	Can be set to true, if the API response should include further details on why the payments failed, if any. Defaults to false.

Request Body

Fields

Name	Description
`trade_id` Optional	Unique identifier of the trade the payment will be allocated to. When `trade_id` is not provided, the initiation is considered as an independent payment. It does not require FX before the payment
`async`	`boolean` flag to create the payment(s) asynchronously; defaults to `false`
`purpose_of_payment` Optional	A purpose of payment. Relevant (and optional) only for independent payments. The acceptable values are Reason for trade
`payments`	A list of payments to create
`payments.beneficiary_id` Required	The ID of the beneficiary
`payments.account_id` Required	The ID of the beneficiary's bank account
`payments.amount` Required	The payment amount
`payments.payment_date` Required	The date on which payment is required
`payments.reference` Required	Payment reference
`payments.email_beneficiary`	Whether the beneficiary should receive and email on payment

Response

The response to a successful request will vary depending on the value of the async value of the request.

HTTP/1.1 204 No Content

If async is set to true, a 204 No Content response will be returned, as the request is being processed asynchronously.

HTTP/1.1 201 Created
Content-Type: application/json

[
    {
        "payment_id": "string",
        "fee_amount": "number",
        "fee_currency": "string",
        "payment_instruction": "string",
        "payment_receipt": "string",
        "status": "string",
        "reference": "string",
        "warning": "string"
    }
]

If async is set to false, a 201 Created response will be returned with the with the following response body.

Fields

Name	Description
`payment_id`	The payment identifier
`fee_amount`	Fee amount
`fee_currency`	Fee currency
`payment_instruction`	URI to download payment instruction
`payment_receipt`	URI to download payment receipt
`status`	The current status of the payment
`reference`	The payment reference
`warning`	A warning is returned only if the requested `payment_date` for an independent payment was not valid and the next available date has been returned

Search or retrieve payments

GET /payments?client_id=$client_id HTTP/1.1
Authorization: string

Search or retrieve all payments for a given client ID

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`page`	The desired page number for pagination. Default value is `1`.
`page_size`	The number of items per page for pagination. Default value is `50`.
`reference`	Filter payments by reference.
`trade_id`	Filter payments by trade_id.
`external_reference_id`	Filter by payment’s external_reference_id. At the moment, it is possible only for payments initiated via the mass payments service.
`mass_payment_id`	Filter by related mass payment's uuid.
`mass_payment_external_reference_id`	Filter by related mass payment's external reference.
`multipayment_id`	Filter by related multipayment_id. Provide only the numerals of the multipayment_id.
`payment_currency`	Filter by payment currency
`from_payment_date`	Only return payments with payment date on or after this from_payment_date. YYYY-MM-DD format.
`to_payment_date`	Only return payments with payment date on or before this to_payment_date. YYYY-MM-DD format.
`from_created_date`	Only return payments with created date on or after this from_created_date. YYYY-MM-DD format.
`to_created_date`	Only return payments with created date on or before this to_created_date. YYYY-MM-DD format.
`pending_only`	If `true`, only return payments which are not yet executed (not in status `Payment complete` OR `Payment rejected` OR `Payment cancelled`). Default value is `false`.
`include_all`	If `true`, return all payments regardless of the payment statuses. Default value is `false`.

Response

HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1

[
    {
        "payment_id": "string",
        "contact_id": "string",
        "trade_id": "string",
        "account_number": "string",
        "amount": "number",
        "bank_identifier": "string",
        "beneficiary_name": "string",
        "created_date": "string",
        "external_reference_id": "string",
        "fee_amount": "number",
        "fee_currency": "string",
        "iban": "string",
        "payment_currency": "string",
        "payment_date": "string",
        "payment_instruction": "string",
        "payment_receipt": "string",
        "status": "string",
        "swift_code": "string",
        "authorised_by": "string",
        "authorised_date": "string",
        "rejected_by": "string",
        "rejected_date": "string",
        "cancelled_by": "string",
        "cancelled_date": "string",
        "authorisation_workflow": "string",
        "invoice_required": "boolean",
        "reference": "string"
    }
]

A successful request will return a 200 OK response with the response body containing list of Payment objects. In addition the total number of entries is available in the header field x-total-count.

Retrieve a payment

GET /payments/$payment_id?client_id=$client_id HTTP/1.1
Authorization: string

Retrieve a payment with a given payment ID

Path Parameters

Parameter	Description
`payment_id` Required	Unique idenifier for payment

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment_id": "string",
    "contact_id": "string",
    "trade_id": "string",
    "account_number": "string",
    "amount": "number",
    "bank_identifier": "string",
    "beneficiary_name": "string",
    "created_date": "string",
    "external_reference_id": "string",
    "fee_amount": "number",
    "fee_currency": "string",
    "iban": "string",
    "payment_currency": "string",
    "payment_date": "string",
    "payment_instruction": "string",
    "payment_receipt": "string",
    "status": "string",
    "swift_code": "string",
    "authorised_by": "string",
    "authorised_date": "string",
    "rejected_by": "string",
    "rejected_date": "string",
    "cancelled_by": "string",
    "cancelled_date": "string",
    "authorisation_workflow": "string",
    "invoice_required": "boolean",
    "reference": "string"
}

A successful request will return a 200 OK response with the response body containing a Payment object.

Authorise or reject a payment

PATCH /payments/$payment_id?client_id=$client_id&action=$action HTTP/1.1
Authorization: string

HTTP/1.1 204 No Content

Authorise or reject a payment with a given payment ID (the requirement to authorise or reject payments depends on your account configuration)

Path Parameters

Parameter	Description
`payment_id` Required	Unique idenifier for payment

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`action` Required	The action to take (`authorise` or `reject`)

Response

HTTP/1.1 204 No Content

A successful request will return a 204 No Content response with an empty response body.

Delete a payment

DELETE /payments/$payment_id?client_id=$client_id HTTP/1.1
Authorization: string

Delete a payment with a given payment ID

Path Parameters

Parameter	Description
`payment_id` Required	Unique idenifier for payment

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Response

HTTP/1.1 204 No Content

A successful request will return a 204 No Content response with an empty response body.

Get the estimate fee of payments

GET /payments/fees_estimate?client_id=$client_id&payment_amount=$payment_amount&payment_currency=$payment_currency HTTP/1.1
Authorization: string

Retrieve the potential payment fee for sending a payment.

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`payment_amount` Required	The amount of the payment
`payment_currency` Required	The currency of the payment
`payment_country`	The destination country of the payment
`payment_intra_Ebury`	`boolean` flag to filter by Ebury intra payments or not

Response

HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "fee_amount": "number",
        "fee_currency": "string",
        "payment_currency": "string",
        "payment_country": "string",
        "payment_amount": "number",
        "payment_instruction": "string",
        "payment_is_intra": "boolean"
    }
]

A successful request will return a 200 OK response with the response body containing a list of Payment Fee objects.

Get the accurate fee of payments

GET /payments/fees?client_id=$client_id&payment_amount=$payment_amount&beneficiary_id=$beneficiary_id HTTP/1.1
Authorization: string

Retrieve the accurate payment fee for sending a payment to a particular beneficiary

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`payment_amount` Required	The amount of the payment
`beneficiary_id` Required	The beneficiary_id to whom payment needs to be made

Response

HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "beneficiary_id": "string",
        "fee_amount": "number",
        "fee_currency": "string",
        "payment_amount": "number",
        "payment_currency": "string",
        "payment_country": "string",
        "payment_is_intra": "boolean"
    }
]

A successful request will return a 200 OK response with the response body containing a list of Payment Fee objects.

Payment Models

Payment

{
    "payment_id": "string",
    "contact_id": "string",
    "trade_id": "string",
    "account_number": "string",
    "amount": "number",
    "bank_identifier": "string",
    "beneficiary_name": "string",
    "created_date": "string",
    "external_reference_id": "string",
    "fee_amount": "number",
    "fee_currency": "string",
    "iban": "string",
    "payment_currency": "string",
    "payment_date": "string",
    "payment_instruction": "string",
    "payment_receipt": "string",
    "status": "string",
    "swift_code": "string",
    "authorised_by": "string",
    "authorised_date": "string",
    "rejected_by": "string",
    "rejected_date": "string",
    "cancelled_by": "string",
    "cancelled_date": "string",
    "authorisation_workflow": "string",
    "invoice_required": "boolean",
    "reference": "string"
}

This model is a representation of a payment.

Fields

Name	Description
`payment_id` Always	Unique identifier for the payment
`contact_id` Always	Unique identifier of the contact who booked the payment
`trade_id` Always	Unique identifier of the trade the payment is allocated to
`multipayment_id`	Unique identifier for the multi payment
`mass_payment_id`	Unique identifier for the mass payment
`account_number`	Account number of the beneficiary
`amount`	Payment amount
`bank_identifier`	The identifier of the beneficiary's bank
`beneficiary_name`	Name of the beneficiary
`created_date`	Payment instruction created date
`external_reference_id`	Unique reference submitted by the client to identify the payment
`fee_amount`	Fee amount
`fee_currency`	Fee currency
`iban`	The IBAN of the beneficiary's bank account
`payment_currency`	Currency the payment was made in
`payment_date`	Target payment date
`payment_instruction`	URI to download payment instruction
`payment_receipt`	URI to download payment receipt
`status`	The current status of the payment
`swift_code`	The SWIFT code of the beneficiary's bank account
`authorised_by`	The user who authorised the payment
`authorised_date`	The date when payment was authorised
`rejected_by`	The user who rejected the payment
`rejected_date`	The date when payment was rejected
`cancelled_by`	The user who cancelled the payment
`cancelled_date`	The date when payment was cancelled
`authorisation_workflow`	The authorisation workflow of the payment Acceptable values: `simple` `4-eyes`
`invoice_required`	Whether or not the payment requires an invoice
`reference`	The payment reference

Status

Status of the payments

Values

Value	Description
`Need more beneficiary information`	Beneficiary information is not complete, more details are required.
`Validating beneficiary information`	Beneficiary information is complete, but not validated yet.
`Waiting for payment date`	Payment is ready to be executed, waiting for payment execution date.
`Payment complete`	Payment has been executed.
`Executing Payment`	Payment is in the process of being executed.
`Payment pending of authorization`	Payment has been verified but not authorised.
`Payment rejected`	Payment has been rejected.
`Payment cancelled`	Payment has been cancelled.

Payment Fee

{
    "fee_amount": "number",
    "fee_currency": "string",
    "payment_amount": "number",
    "payment_country": "string",
    "payment_currency": "string",
    "payment_instruction": "number",
    "payment_is_intra": "boolean"
}

This model is a representation of a payment fee.

Fields

Name	Description
`fee_amount` Always	Fee amount
`fee_currency` Always	Fee currency
`payment_amount`	Payment amount
`payment_currency` Always	Currency the payment was made in
`payment_country` Always	The destination country of the payment
`payment_instruction` Always	Payment instruction
`payment_is_intra`	True if payment is Ebury intra payments, False otherwise

Managing Contacts

The Contacts API allows you to amend aspects of the user profiles active on your account.

Please note that due to controls implemented in Ebury's operational procedures it's not currently possible to create or delete (POST/DELETE) contacts using the API

Get Contacts

GET /contacts?client_id=$client_id HTTP/1.1
Authorization: string

Get all contacts for a given client.

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "name": "string",
        "first_name": "string",
        "last_name": "string",
        "email_address": "string",
        "work_contact_number": "string",
        "home_contact_number": "string",
        "mobile_contact_number": "string",
        "address_line_1": "string",
        "address_line_2": "string",
        "city": "string",
        "country_code": "string",
        "country_name": "string",
        "post_code": "string",
        "password_reset_required": "boolean",
        "language": "string",
        "locale": "string",
        "time_zone": "string",
        "has_online_access": "boolean",
        "can_authorise_payments": "boolean",
        "can_make_same_currency_payments": "boolean",
        "can_make_independent_payments": "boolean",
        "can_manage_beneficiaries": "boolean",
        "can_manage_beneficiaries_groups": "boolean",
        "can_manage_contacts": "boolean",
        "can_manage_fix_forwards": "boolean",
        "can_manage_multipayments": "boolean",
        "can_manage_payments": "boolean",
        "can_manage_permissions": "boolean",
        "can_trade": "boolean",
        "contact_id": "string"
    }
]

A successful request will return a 200 OK response with the response body containing a list of Contact objects.

Get a single contact

GET /contacts/$contact_id?client_id=$client_id HTTP/1.1
Authorization: string

Get a single contact by contact ID.

Path Parameters

Parameter	Description
`contact_id` Required	The ID of the contact

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "string",
    "first_name": "string",
    "last_name": "string",
    "email_address": "string",
    "work_contact_number": "string",
    "home_contact_number": "string",
    "mobile_contact_number": "string",
    "address_line_1": "string",
    "address_line_2": "string",
    "city": "string",
    "country_code": "string",
    "country_name": "string",
    "post_code": "string",
    "password_reset_required": "boolean",
    "language": "string",
    "locale": "string",
    "time_zone": "string",
    "has_online_access": "boolean",
    "can_authorise_payments": "boolean",
    "can_make_same_currency_payments": "boolean",
    "can_make_independent_payments": "boolean",
    "can_manage_beneficiaries": "boolean",
    "can_manage_beneficiaries_groups": "boolean",
    "can_manage_contacts": "boolean",
    "can_manage_fix_forwards": "boolean",
    "can_manage_multipayments": "boolean",
    "can_manage_payments": "boolean",
    "can_manage_permissions": "boolean",
    "can_trade": "boolean",
    "contact_id": "string"
}

A successful request will return a 200 OK response with the response body containing a Contact object.

Update a contact

PATCH /contacts/$contact_id?client_id=$client_id HTTP/1.1
Authorization: string

Content-Type: application/json

{
    "language": "string",
    "locale": "string",
    "time_zone": "string",
    "has_online_access": "boolean",
    "can_authorise_payments": "boolean",
    "can_make_same_currency_payments": "boolean",
    "can_manage_beneficiaries": "boolean",
    "can_manage_beneficiaries_groups": "boolean",
    "can_manage_contacts": "boolean",
    "can_manage_fix_forwards": "boolean",
    "can_manage_multipayments": "boolean",
    "can_manage_payments": "boolean",
    "can_manage_permissions": "boolean",
    "can_trade": "boolean",
}

Update a single contact identified by contact_id.

The fields language, locale, and time_zone may be omitted.

If omitted in the API request, the rest of the fields related to permissions will be updated to their default values (which is ‘false’)

We do not currently support PUT. This may be supported in a later release.

Request Headers

Header	Description
`Content-Type` Required	`application/json`

Path Parameters

Parameter	Description
`contact_id` Required	The ID of the contact

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Request Body

Fields

Name	Description
`language`	Language expressed as ISO 639-1 two-character code
`locale`	Locale expressed as ISO 639-1 two-character code
`time_zone`	The time zone of the contact
`has_online_access`	Contact has access to Ebury Online
`can_authorise_payments`	Contact can authorise payments
`can_make_same_currency_payments`	Contact can create trades and assign same currency payments
`can_manage_beneficiaries`	Contact can manage beneficiaries
`can_manage_beneficiaries_groups`	Contact can manage beneficiaries groups
`can_manage_contacts`	Contact can manage contacts
`can_manage_fix_forwards`	Contact can manage fixed forwards
`can_manage_multipayments`	Contact can manage multipayments
`can_manage_payments`	Contact can manage payments
`can_manage_permissions`	Contact can manage permissions
`can_trade`	Contact can execute trades

Response

HTTP/1.1 204 No Content

A successful request will return a 204 No Content response with an empty response body.

Contact Models

Contact

{
    "name": "string",
    "first_name": "string",
    "last_name": "string",
    "email_address": "string",
    "work_contact_number": "string",
    "home_contact_number": "string",
    "mobile_contact_number": "string",
    "address_line_1": "string",
    "address_line_2": "string",
    "city": "string",
    "country_code": "string",
    "country_name": "string",
    "post_code": "string",
    "password_reset_required": "boolean",
    "language": "string",
    "locale": "string",
    "time_zone": "string",
    "has_online_access": "boolean",
    "can_authorise_payments": "boolean",
    "can_make_same_currency_payments": "boolean",
    "can_make_independent_payments": "boolean",
    "can_manage_beneficiaries": "boolean",
    "can_manage_beneficiaries_groups": "boolean",
    "can_manage_contacts": "boolean",
    "can_manage_fix_forwards": "boolean",
    "can_manage_multipayments": "boolean",
    "can_manage_payments": "boolean",
    "can_manage_permissions": "boolean",
    "can_trade": "boolean",
    "contact_id": "string"
}

This model is a representation of a contact.

Fields

Name	Description
`name`	Full name of the contact
`first_name`	First name of the contact
`last_name`	Last name of the contact
`email_address` Always	Email address/username of the contact
`work_contact_number`	The work contact number of the contact
`home_contact_number`	The home contact number of the contact
`mobile_contact_number`	The mobile contact number of the contact
`address_line_1`	The first address line of the contact
`address_line_2`	The second address line of the contact
`city`	The city name of the contact
`country_code`	Country as ISO 3166 two-character code
`country_name`	Full name of the country
`post_code`	The postcode of the contact
`password_reset_required`	`true` if contact needs to reset their password, `false` otherwise
`language`	Language expressed as ISO 639-1 two-character code
`locale`	Locale expressed as ISO 639-1 two-character code
`time_zone`	The time zone of the contact
`has_online_access`	Contact has access to Ebury Online
`can_authorise_payments`	Contact can authorise payments
`can_make_same_currency_payments`	Contact can create trades and assign same currency payments
`can_make_independent_payments`	Contact can make independent payments
`can_manage_beneficiaries`	Contact can manage beneficiaries
`can_manage_beneficiaries_groups`	Contact can manage beneficiaries groups
`can_manage_contacts`	Contact can manage contacts
`can_manage_fix_forwards`	Contact can manage fixed forwards
`can_manage_multipayments`	Contact can manage multipayments
`can_manage_payments`	Contact can manage payments
`can_manage_permissions`	Contact can manage permissions
`can_trade`	Contact can execute spot trades
`contact_id`	Unique identifier for the Contact

ContactUpdate

{
    "language": "string",
    "locale": "string",
    "time_zone": "string",
    "has_online_access": "boolean",
    "can_authorise_payments": "boolean",
    "can_make_same_currency_payments": "boolean",
    "can_manage_beneficiaries": "boolean",
    "can_manage_beneficiaries_groups": "boolean",
    "can_manage_contacts": "boolean",
    "can_manage_fix_forwards": "boolean",
    "can_manage_multipayments": "boolean",
    "can_manage_payments": "boolean",
    "can_manage_permissions": "boolean",
    "can_trade": "boolean",
}

This model is a representation of the updateable data of a contact.

Fields

Name	Description
`language`	Language expressed as ISO 639-1 two-character code
`locale`	Locale expressed as ISO 639-1 two-character code
`time_zone`	The time zone of the contact
`has_online_access`	Contact has access to Ebury Online
`can_authorise_payments`	Contact can authorise payments
`can_make_same_currency_payments`	Contact can create trades and assign same currency payments
`can_manage_beneficiaries`	Contact can manage beneficiaries
`can_manage_beneficiaries_groups`	Contact can manage beneficiaries groups
`can_manage_contacts`	Contact can manage contacts
`can_manage_fix_forwards`	Contact can manage fixed forwards
`can_manage_multipayments`	Contact can manage multipayments
`can_manage_payments`	Contact can manage payments
`can_manage_permissions`	Contact can manage permissions
`can_trade`	Contact can execute trades

Viewing Documents

Get a document

GET /documents?client_id=$client_id&type=$type&id=$id HTTP/1.1
Authorization: string

Get a document for a given client

Query Parameters

Parameter	Description
`type` Required	The document type Acceptable values: `pi` (payment instruction) `pr` (payment receipt) `tr` (trade receipt)
`id` Required	The ID of the entity that generated this document e.g. payment, trade, etc.
`client_id` Required	Your client identifier

Response

HTTP/1.1 200 OK
Content-Type: text/plain

string

A successful request will return a 200 OK response with the response body containing a Base 64 encoded string containining the requested document.

Executing Mass Beneficiaries

Submit a Mass Beneficiary instruction

Submit a new mass beneficiary instruction that can be processed in async or sync mode.

Query Parameters


`client_id` Required	The ID of the client

Body Request

The body of the request must contain a list of the Beneficiaries.

POST /mass-beneficiaries?client_id=$client_id HTTP/1.1
Content-Type: application/json

[
  {
    "name": "string",
    "email_addresses": [
      "string"
    ],
    "email_notification": "boolean",
    "address_line_1": "string",
    "street_name": "string",
    "state_region": "string",
    "building_number": "string",
    "floor": "string",
    "apartment_office_number": "string",
    "post_code": "string",
    "country_code": "string",
    "account_number": "string",
    "bank_address_line_1": "string",
    "bank_country_code": "string",
    "bank_currency_code": "string",
    "bank_identifier": "string",
    "bank_name": "string",
    "correspondent_account": "string",
    "correspondent_swift_code": "string",
    "iban": "string",
    "inn": "string",
    "kbk": "string",
    "kio": "string",
    "kpp": "string",
    "purpose_of_payment": "string",
    "reason_for_trade": "string",
    "reference_information": "string",
    "beneficiary_reference": "string",
    "russian_central_bank_account": "string",
    "swift_code": "string",
    "vo": "string"
  }
]

Response

A successful request will return a "202 Accepted" response with the MassBeneficiary model.

Retrieve all Mass Beneficiaries submissions

Obtain the full list of mass beneficiaries async process status for a given client_id. The status field will provide the latest status whether processing is complete or still running.

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client.
`page`	The desired page number for pagination. Default value is `1`.
`page-size`	The number of items per page for pagination. Default value is `50`.

GET /mass-beneficiaries?client_id=$client_id

Response

A successful request will return a "200 OK" response with a list of the Mass Beneficiary objects.

Retrieve a single Mass Beneficiary submission

Retrieve a mass beneficiary resource for a given mass_beneficiary_id. The status field will provide the latest status.

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client.
`mass_beneficiary_id` Required	The unique ID of the mass beneficiary.

GET /mass-beneficiaries/$mass_beneficiary_id?client_id=$client_id

Response

A successful request will return a "200 OK" response with the Mass Beneficiary Model.

Retrieve errors in beneficiaries creation using Mass Beneficiaries service

View all the errored beneficiaries in a mass beneficiaries instruction.

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client.
`page`	The desired page number for pagination. Default value is `1`.
`page-size`	The number of items per page for pagination. Default value is `50`.

GET /mass-beneficiaries/$mass_beneficiary_id/errors?client_id=$client_id

Response

A successful request will return a "200 OK" response with the response body containing a list of BeneficiaryCreationError objects. In addition, the total number of entries is available in the header field x-total-count.

[
  {
    "code": "string",
    "details": "string",
    "message": "string",
    "request_index": "number"
  }
]

Retrieve successfully created Beneficiaries

View all the created beneficiaries in a mass beneficiaries instruction.

Query Parameters


`client_id` Required	The ID of the client.
`page`	The desired page number for pagination. Default value is `1`.
`page-size`	The number of items per page for pagination. Default value is `50`.

GET /mass-beneficiaries/$mass_beneficiary_id/beneficiaries?client_id=$client_id

Response

A successful request will return a "200 OK" response with the response body containing a list of BeneficiaryCreated objects. In addition, the total number of entries is available in the header field x-total-count.

[
  {
    "beneficiary_id": "string",
    "links": {
      "beneficiary_href": "/beneficiaries/$beneficiary_id"
    },
    "request_index": 0
  }
]

Mass Beneficiary Models

MassBeneficiary

This model is a representation of a mass beneficiary.

Fields

Name	Description
`mass_beneficiary_id` Always	Unique UUID of the mass beneficiary.
`error` Always	The generic error message for the mass beneficiary request, if any.
`links` Always	The MassBeneficiaryLinks.
`summary` Always	The MassBeneficiarySummary.
`status` Always	The MassBeneficiaryStatus.

{
  "mass_beneficiary_id": "uuid",
  "error": {
    "code": "string",
    "message": "string",
    "details": "string"
  },
  "links": {
    "errors_href": "/mass-beneficiaries/$mass_beneficiary_id/errors",
    "created_href": "/mass-beneficiaries/$mass_beneficiary_id/beneficiaries",
  },
  "summary": {
    "received": "number",
    "errored": "number",
    "created": "number"
  },
  "status": "string"
}

MassBeneficiaryStatus

The possible values for the "status" of every mass beneficiary instruction.

Values

Value	Description
`pending`	The Mass Beneficiary is pending to be processed.
`creating`	The Mass Beneficiary is being processed.
`created`	The Mass Beneficiary has been successfully processed.
`failed`	The Mass Beneficiary has failed during processing.
`unknown`	The Mass Beneficiary has an unknown status.

MassBeneficiarySummary

This is an object containing categorized counters for the mass beneficiary.

Fields

Name	Description
`received` Always	Total count of received beneficiaries.
`created` Always	Total count of created beneficiaries.
`errored` Always	Total count of errored beneficiaries.

MassBeneficiaryLinks

This is an object containing links for the mass beneficiary related information. Each link helps the user agent to fetch resources related to errored beneficiaries, and also those created successfully. The mass_beneficiary_id does not need to be stored as the said resources may be accessed with the provided links.

Fields

Name	Description
`errors_href` Always	The link to the errors endpoint `/mass-beneficiaries/$mass_beneficiary_id/errors`
`created_href` Always	The link to the result endpoint `/mass-beneficiaries/$mass_beneficiary_id/beneficiaries`

BeneficiaryCreationError

Creation errors of every beneficiary.

Fields

Name	Description
`code` Always	A short code for the error.
`details` Always	Error details.
`message` Always	The error message.
`request_index` Always	The original position of the beneficiary on the submission file. It starts at 0.

BeneficiaryCreated

Created beneficiaries.

Fields

Name	Description
`request_index` Always	The original position of the beneficiary on the submission file. It starts at 0.
`beneficiary_id` Always	The ID of the created beneficiary.
`links` Always	The BeneficiaryCreatedLinks.

BeneficiaryCreatedLinks

This is an object containing links for the created beneficiary.

Fields

Name	Description
`beneficiary_href`	The link to the single beneficiary endpoint `/beneficiaries/$beneficiary_id`

Executing Mass Payments

Submit a Mass Payment instruction

Create a new mass payment instruction in async mode only. A mass payment instruction requires either a single sell currency or existing trade ID to be specified in order to create an instruction. Note that within a mass payment instruction it is not possible to use different sell currencies per payment.

Query Parameters


`client_id` Required	The ID of the client

Body Request

The body of the request must contain a list of the objects containing the following fields:

Fields


`external_reference_id`	Unique external reference ID submitted by the client.
`auto_commit` Always	If true, and if there are no errors identified at the time of processing the request, the payments will be created. If false, the mass payment process will stop after validation and creation of the beneficiary and will require review/confirmation.
`sell_currency`	Mandatory if no trade_id is provided.
`trade_id`	Mandatory if no sell_currency is provided.
`payment_instructions` Always	Array of Payment Instructions given by the client.

POST/ mass-payments?client_id=client_id HTTP/1.1
Content-Type: application/json

{
   "external_reference_id":"string",
   "auto_commit":"boolean",
   "sell_currency": "GBP",
   "trade_id" :"string",
   "payment_instructions": [
      {
         "account_number":"string",
         "bank_address":"string",
         "bank_code":"string",
         "bank_country":"string",
         "bank_name":"string",
         "beneficiary_address":"string",
         "beneficiary_street_name":"string",
         "beneficiary_building_number":"string",
         "beneficiary_floor":"string",
         "beneficiary_apartment_office_number":"string",
         "beneficiary_city":"string",
         "beneficiary_state_region":"string",
         "beneficiary_post_code":"string",
         "beneficiary_name":"string",
         "beneficiary_country":"string",
         "beneficiary_reference":"string",
         "direction":"string",
         "external_reference_id":"string",
         "iban":"string",
         "inn":"string",
         "kio":"string",
         "payment_currency":"string",
         "payment_amount":"number",
         "payment_reference":"string",
         "purpose_of_payment":"Purpose of Payment",
         "reason_for_trade":"string",
         "russian_central_bank_account":"string",
         "swift_code":"string",
         "trade_type":"string",
         "value_date":"string",
         "vo":"string"
      }
   ]
}

Response

A successful request will return a “202 Accepted” response with the response body containing a list of objects.

Fields


`mass_payment_id` Always	Unique UUID of the mass payment.
`external_reference_id` Always	Unique ID of the external reference submitted by the client.
`mass_payment_status` Always	The MassPaymentStatus.

HTTP/1.1 202 ACCEPTED

{
   "mass_payment_id":"uuid",
   "external_reference_id":"string",
   "mass_payment_status":"string"
}

Retrieve all Mass Payments submissions

Obtain the full list of mass payments async process status for a given client_id. The MassPaymentStatus field will provide the latest status whether processing is complete or still running. API consumers can retrieve a mass payment using an external_reference_id provided at the time of the mass payment submission.

Query Parameters


`client_id` Required	The ID of the client
`external_reference_id`	If the same external_reference_id is being used in multiple mass payment requests, then more than one mass payment will be returned.
`sell_currency`	The sell currency of the mass payment ISO 4217.
`page`	The desired page number for pagination. Default value is `1`.
`page-size`	The number of items per page for pagination. Default value is `50`.

Response

The body of the request must contain a list of the objects containing the following fields:

Fields


`mass_payment_id` Always	Unique UUID of the mass payment.
`external_reference_id`	Unique ID of the external reference submitted by the client.
`mass_payment_status` Always	The MassPaymentStatus.
`sell_currency`	The sell currency of the mass payment.
`trades_created`	Total number of created trades.
`payments_summary`	The PaymentsSummaryTypes
`links`	Links to the PaymentsSummaryLinks

Retrieve a single Mass Payment submission

Obtain a mass payments async process status for a given mass_payment_id. The MassPaymentStatus field will provide the latest status whether processing is complete or still running.

Query Parameters


`client_id` Required	The ID of the client
`mass_payment_id` Required	The unique ID of the mass payment. Non mandatory if external-reference-id is provided.

GET/mass-payments?client_id=client_id&mass_payment_id={mass_payment_id}
Content-Type: application/json

Response

A successful request will return a “200 OK” response with the response body containing a list of MassPayment objects.

Fields


`mass_payment_id` Always	Unique UUID of the mass payment.
`external_reference_id`	Unique ID of the external reference submitted by the client.
`mass_payment_status` Always	The MassPaymentStatus.
`sell_currency`	The sell currency of the mass payment.
`trades_created`	Total number of created trades.
`payments_summary`	The PaymentsSummaryTypes
`links`	Links to the PaymentsSummaryLinks

HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1

[
  {
    "mass_payment_id":"uuid",
    "external_reference_id":"string",
    "error": {
       "code": "string",
       "message": "string",
       "details": "string"
    },
    "mass_payment_status":"string",
    "sell_currency":"string",
    "trades_created":"number",
    "payments_summary":
    {
        "payments_received":"number",
        "payments_processed":"number",
        "payments_errored":"number",
        "payments_created":"number"
    }
    "links":
    {
      "payments_errored_href":"APP_URL/mass-payments/$mass_payment_id/errors?client_id=$client_id",
      "payments_created_href":"APP_URL/payments?client_id=$client_id&mass_payment_id=$mass_payment_id",
      "trades_href":"APP_URL/trades?client_id=$client_id&mass_payment_id=$mass_payment_id",
      "funding_account_href" : "APP_URL/mass-payments/$mass_payment_id/funding-account?client_id=$client_id"
    }
  }
]

Retrieve payments submitted using Mass Payment service

Obtain all the payment instructions submitted with Submit a Mass Payment Instruction for a given mass_payment_id. You may also filter instructions by payment_currency.

Query Parameters


`client_id` Required	The ID of the client
`page`	The desired page number for pagination. Default value is `1`.
`page-size`	The number of items per page for pagination. Default value is `50`.
`payment_currency`	The currency of the payment.

GET/mass_payments/$mass_payment_id/payments-received?client_id=$client_id
Content-Type: application/json

Response

A successful request will return a “200 OK” response with the response body containing a list of PaymentInstruction objects. In addition, the total number of entries retrieved is available in header field x-total-count.

HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1

[
   {
      "account_number":"string",
      "bank_address":"string",
      "bank_code":"string",
      "bank_country":"string",
      "bank_name":"string",
      "beneficiary_address":"string",
      "beneficiary_street_name":"string",
      "beneficiary_building_number":"string",
      "beneficiary_floor":"string",
      "beneficiary_apartment_office_number":"string",
      "beneficiary_city":"string",
      "beneficiary_state_region":"string",
      "beneficiary_post_code":"string",
      "beneficiary_name":"string",
      "beneficiary_country":"string",
      "beneficiary_reference":"string",
      "direction":"string",
      "external_reference_id":"string",
      "iban":"string",
      "inn":"string",
      "kio":"string",
      "payment_currency":"string",
      "payment_amount":"number",
      "payment_reference":"string",
      "purpose_of_payment":"Purpose of Payment",
      "reason_for_trade":"string",
      "russian_central_bank_account":"string",
      "swift_code":"string",
      "trade_type":"string",
      "value_date":"string",
      "vo":"string"
   }
]

Retrieve errors in payments submitted using Mass Payment service

View all the errored payments in a mass payment instruction possibly by filtering with payment _currency.

Query Parameters


`client_id` Required	The ID of the client
`page`	The desired page number for pagination. Default value is `1`.
`page-size`	The number of items per page for pagination. Default value is `50`.
`payment_currency`	The currency of the payment.

GET/mass-payments/$mass_payment_id/errors?client-id=$client_id
Content-Type: application/json

Response

A successful request will return a “200 OK” response with the response body containing a list of objects. In addition, the total number of entries is available in the header field x-total-count.

Fields


`Payment Instruction` Always	Payment Instructions given by the client.
`errors`	Array of objects. Will display the error code and error message.

HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1

[
   {
      "account_number":"string",
      "bank_address":"string",
      "bank_code":"string",
      "bank_country":"string",
      "bank_name":"string",
      "beneficiary_address":"string",
      "beneficiary_street_name":"string",
      "beneficiary_building_number":"string",
      "beneficiary_floor":"string",
      "beneficiary_apartment_office_number":"string",
      "beneficiary_city":"string",
      "beneficiary_state_region":"string",
      "beneficiary_post_code":"string",
      "beneficiary_name":"string",
      "beneficiary_country":"string",
      "beneficiary_reference":"string",
      "direction":"string",
      "external_reference_id":"string",
      "iban":"string",
      "inn":"string",
      "kio":"string",
      "payment_currency":"string",
      "payment_amount":"number",
      "payment_reference":"string",
      "purpose_of_payment":"Purpose of Payment",
      "reason_for_trade":"string",
      "russian_central_bank_account":"string",
      "swift_code":"string",
      "trade_type":"string",
      "value_date":"string",
      "vo":"string",
      "errors":[
         {
            "code":"INVALID_VALUE_",
            "message":"Invalid Value Date"
         }
      ]
   }
]

Confirm a Mass Payment Instruction

Review a processed mass payment and then confirm the instruction to allow trade and payments creation.

You have to confirm a mass payment instruction when 1) The auto_commit field is set to false, 2) The auto_commit field is set to true and errors are identified at the time of processing request.

Query Parameters


`client_id` Required	The ID of the client

POST/mass-payments/{$mass_payment_id}/confirm?client-id=$client_id
Content-Type: application/json

Response

A successful request will return a “202 Accepted” response with the response body containing the mass_payment_status object.

Fields


`mass_payment_status` Always	The MassPaymentStatus.

HTTP/1.1 202 ACCEPTED
Content-Type: application/json

{
   "mass_payment_status":"string"
}

Retrieve funding account for trades linked to Mass Payment

Retrieve the funding account where money needs to be deposited for trades created as part of the Mass payment Instruction.

Query Parameters


`client_id` Required	The ID of the client

GET /mass-payments/$mass_payment_id/funding-account
Content-Type: application/json

Response

A successful request will return a “200 OK” response with the response body containing a list of objects.

Fields


`account_number`	The funding account number
`bank_identifier`	The funding account bank identifier
`bank_identifier_type`	The funding account bank identifier type
`iban`	The funding account IBAN
`swift_code`	The funding account swift code

HTTP/1.1 200 OK
Content-Type: application/json

{
    "account_number": "93475247",
    "bank_identifier": "200605",
    "bank_identifier_type": "Sort Code",
    "iban": "GB82BARC20060593475247",
    "swift_code": "BARCGB22"
}

Mass Payment Model

This model is a representation of a mass payment.

Fields


`mass_payment_id`	Unique UUID of the mass payment.
`external_reference_id`	Unique ID of the external reference submitted by the client.
`error`	The generic error message for the mass payment request, if any.
`mass_payment_status`	The MassPaymentStatus.
`sell_currency`	The sell currency of the mass payment.
`trades_created`	Total number of created trades.
`payments_summary`	The PaymentsSummaryTypes
`links`	Links to the PaymentsSummaryLinks

MassPaymentStatus

The mass_payment_status values of the mass payment instruction.

Values


`queued for processing`	The mass payment submission request has been received by Ebury and it has been queued for payment instruction, validation and beneficiary creation.
`processing`	The mass payment request is being processed. PaymentsSummaryTypes will have value=0 because the mass payment instruction validation and beneficiary creation is not yet complete.
`processed`	The payment has been processed. PaymentsSummaryTypes will now contain values (except for payments_created and trade_created which will have value=0) because the payment has not yet reached “created”.
`queued for creating`	The mass payment submission request has been received by Ebury and it has been queued for payment instruction validation and beneficiary creation.
`creating`	The mass payment has been picked up from the queue and it has been submitted for trade and payment creation. PaymentsSummaryTypes will now contain values (except for payments_created and trade_created which will have value=0) because the payment has not yet reached “created”.
`created`	The payment and trade have been created. PaymentsSummaryTypes will now contain relevant values as the process is now complete. Also PaymentsSummeryLinks object will contain a new property funding_account_href.

PaymentsSummary Types

This is an enumeration of PaymentsSummary types.

Fields


`payments_received`	Total count of received payments
`payments_processed`	Total count of processed payments
`payments_errored`	Total count of errored payments
`payments_created`	Total count of created payments

PaymentsSummary Links

This is an enumeration of PaymentsSummary Links. Each link helps the user agent to fetch resources related to payment errors, payments created successfully, trade and funding accounts associated with the mass payment id. The mass_payment_id does not need to be stored as the said resources may be accessed with the provided links.

Fields


`payments_errored_href**`	/mass-payments/$mass_payment_id/errors
`payments_created_href*`	/payments?mass_payment_id=$mass_payment_id
`trades_href*`	/trades?client_id=$client_id&mass_payment_id=$mass_payment_id
`funding_account_href*`	/mass-payments/$mass_payment_id/funding_account

**Following URL response will return back data when mass_payment_status is "processed" and includes errors.

*Following URL response will return back data when mass_payment_status is "created".

Payment Instructions Model

This is a representation of a payment instruction model. When the Payment Instruction model is used as input, fields marked as REQUIRED are mandatory.

Fields

Name	Description
`account_id`	The ID of the beneficiary's bank account. When this is provided, beneficiary details like account number, beneficiary name should not be.
`beneficiary_id`	The ID of the beneficiary. When this is provided, beneficiary details like account number, beneficiary name should not be.
`account_number`	Account number. When this is provided, beneficiary_id, account_id should not be.
`bank_address`	The bank address of the beneficiary. When this is provided, beneficiary_id, account_id should not be.
`bank_code`	The bank code of the beneficiary (UK sort code, US ABA/FedWire, etc.). When this is provided, beneficiary_id, account_id should not be.
`bank_country`	The bank country of the beneficiary in ISO 3166-1 format (two character alpha code). When this is provided, beneficiary_id, account_id should not be.
`bank_name`	Name of the bank account holder. When this is provided, beneficiary_id, account_id should not be.
`beneficiary_address`^*	The beneficiary address. When this is provided, beneficiary_id, account_id should not be. (deprecated)*
`beneficiary_street_name`^*	The street name of the beneficiary.
`beneficiary_building_number`^*	The building number of the beneficiary.
`beneficiary_floor`^*	The floor of the beneficiary.
`beneficiary_apartment_office_number`^*	The apartment/office number of the beneficiary.
`beneficiary_city`^* Required	The city of the beneficiary.
`beneficiary_state_region`^*	The state/region of the beneficiary.
`beneficiary_post_code`^*	The postcode of the beneficiary.
`beneficiary_country` Required	The beneficiary country in ISO 3166-1 format (two character alpha code). When this is provided, beneficiary_id, account_id should not be.
`beneficiary_name`	The beneficiary name. When this is provided, beneficiary_id, account_id should not be.
`beneficiary_reference`	Permanent reference to add to a beneficiary for all future payments. When this is provided, beneficiary_id, account_id should not be.
`direction` Required	Acceptable values: buy sell *Direction field determines whether the payment_amount reflects the amount of currency to buy or amount of currency to sell. Example provided in notes.
`external_reference_id`	Unique reference submitted by the client to identify the payment.
`iban`	When this is provided, beneficiary_id, account_id should not be.
`inn`	Unique Taxpayer Personal Identification Number for legal entities registered in Russia.
`kio`	Tax ID for foreign legal entities in Russia.
`payment_currency` Required	Buy currency code ISO 4217
`payment_amount` Required	number
`payment_reference` Required	Payment reference
`purpose_of_payment`	The purpose of payment is mandatory when the beneficiary account has specific currency types. See the section PurposeOfPayment for the currencies and their acceptable values.
`reason_for_trade` Required	Reason for trade. See ReasonForTradeValues for acceptable values.
`russian_central_bank_account`	20-digit code for Russian banks.
`swift_code`	When this is provided, beneficiary_id, account_id should not be.
`trade_type` Required	Type of trade. Acceptable values: spot
`value_date` Required	Date of the payment (YYYY-MM-DD)
`vo`	Code of currency transaction established by the Central Bank of Russia to describe the purpose of the payment.

* This field and the related rule becomes operational from October 2024. Further communication will follow over emails. Please note, it does not apply to Ebury Mass Payments customers in Production.

HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1

[
   {
      "account_number":"string",
      "bank_address":"string",
      "bank_code":"string",
      "bank_country":"string",
      "bank_name":"string",
      "beneficiary_address":"string",
      "beneficiary_street_name":"string",
      "beneficiary_building_number":"string",
      "beneficiary_floor":"string",
      "beneficiary_apartment_office_number":"string",
      "beneficiary_city":"string",
      "beneficiary_state_region":"string",
      "beneficiary_post_code":"string",
      "beneficiary_name":"string",
      "beneficiary_country":"string",
      "beneficiary_reference":"string",
      "direction":"string",
      "external_reference_id":"string",
      "iban":"string",
      "inn":"string",
      "kio":"string",
      "payment_currency":"string",
      "payment_amount":"number",
      "payment_reference":"string",
      "purpose_of_payment":"Purpose of Payment",
      "reason_for_trade":"string",
      "russian_central_bank_account":"string",
      "swift_code":"string",
      "trade_type":"string",
      "value_date":"string",
      "vo":"string"
   }
]

*Notes

Example:

At the time of submission of mass-payment (POST /mass-payment) sell_currency field is set as GBP or trade_id provided contains sell_currency as GBP. In the payment instruction payment_currency is set as EUR, payment_amount is set as 100 and direction is set as sell.

{
    "auto_commit": "false",
    "sell_currency": "GBP",
    "external_reference_id": "",
    "payment_instructions": [
        {
            "account_number": "",
            "bank_address": "",
            "bank_code": "",
            "bank_country": "IT",
            "bank_name": "",
            "beneficiary_address": "",
            "beneficiary_street_name": "string",
            "beneficiary_building_number": "string",
            "beneficiary_floor": "string",
            "beneficiary_apartment_office_number": "string",
            "beneficiary_city": "string",
            "beneficiary_state_region": "string",
            "beneficiary_post_code": "string",
            "beneficiary_name": "Beneficiary Name",
            "beneficiary_country": "IT",
            "direction": "sell",
            "external_reference_id": "",
            "iban": "IT28E0300203280787878415564",
            "payment_currency": "EUR",
            "payment_amount": 100,
            "reason_for_trade": "ben1",
            "reference": "reference",
            "swift_code": "UNCRITMMXXX",
            "value_date": null,
            "trade_type": "spot"
        }
    ]
}

In this case the client is giving an instruction to calculate EUR amount equivalent to 100 GBP. The payment_amount will be calculated based on the exchange rate of converting 100 GBP to EUR.

[
    {
        "account_number": "",
        "amount": 116.21,
        "authorisation_workflow": "4-eyes",
        "authorised_by": null,
        "authorised_date": null,
        "bank_identifier": "",
        "beneficiary_name": "Beneficiary Name",
        "cancelled_by": null,
        "cancelled_date": null,
        "contact_id": "EBPCON36429",
        "created_date": "2021-08-20",
        "external_reference_id": "",
        "fee_amount": 12.85,
        "fee_currency": "EUR",
        "iban": "IT03V0300203280998885565948",
        "invoice_required": false,
        "payment_currency": "EUR",
        "payment_date": "2021-08-24",
        "payment_id": "PI2305652",
        "payment_instruction": "/documents?type=pi&id=PI2305652&client_id=EBPCLI00003",
        "payment_receipt": "/documents?type=pr&id=PI2305652&client_id=EBPCLI00003",
        "reference": "reference",
        "rejected_by": null,
        "rejected_date": null,
        "status": "Validating beneficiary information",
        "swift_code": "UNCRITMMXXX",
        "trade_id": "EBPOTR2162767"
    }
]

Executing Multipayments

Create a multi payment instruction

POST /multipayments?client_id=$client_id&accept_immediately=true HTTP/1.1
Authorization: string

Content-Type: application/json

[
    {
        "account_number": "string",
        "bank_address": "string",
        "bank_code": "string",
        "bank_country": "string",
        "bank_name": "string",
        "beneficiary_address": "string",
        "beneficiary_street_name": "string",
        "beneficiary_building_number": "string",
        "beneficiary_floor": "string",
        "beneficiary_apartment_office_number": "string",
        "beneficiary_city": "string",
        "beneficiary_state_region": "string",
        "beneficiary_post_code": "string",
        "beneficiary_name": "string",
        "beneficiary_country": "string",
        "beneficiary_reference": "string",
        "direction": "string",
        "iban": "string",
        "inn": "string",
        "kio": "string",
        "payment_currency": "string",
        "payment_amount": "number",
        "payment_reference": "string",
        "purpose_of_payment": "Purpose of Payment",
        "reason_for_trade": "string",
        "russian_central_bank_account": "string",
        "swift_code": "string",
        "trade_type": "string",
        "value_date": "string",
        "vo": "string"
    }
]

Create a new multi payment instruction. Requires either a sell currency or existing trade ID to create the instruction

Request Headers

Header	Description
`Content-Type` Required	`application/json`

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client
`trade_id`	Trade ID to book payments against. Omit if trade should be executed to fund payments
`sell_currency`	If `trade_id` omitted, a sell currency must be supplied
`accept_partial`	Accept a partially successful instruction. If `true`, send successful instructions for payment. If `false`, reject the entire instruction. Default value is `false`.
`accept_immediately` Required	Mandatory, set to `true`. Accept the quote immediately, do not require confirmation.

Request Body

The body of the request must contain a list of NewMultiPaymentItem.

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
    "multipayment_id": "integer",
    "account_details": {
        "account_number": "string",
        "bank_identifier": "string",
        "bank_identifier_type": "string",
        "iban": "string",
        "swift_code": "string"
    },
    "invalid_payments": [
        {
            "account_number": "string",
            "bank_address": "string",
            "bank_code": "string",
            "bank_country": "string",
            "bank_name": "string",
            "beneficiary_address": "string",
            "beneficiary_street_name": "string",
            "beneficiary_building_number": "string",
            "beneficiary_floor": "string",
            "beneficiary_apartment_office_number": "string",
            "beneficiary_city": "string",
            "beneficiary_state_region": "string",
            "beneficiary_post_code": "string",
            "beneficiary_name": "string",
            "beneficiary_country": "string",
            "beneficiary_reference": "string",
            "direction": "string",
            "iban": "string",
            "inn": "string",
            "kio": "string",
            "payment_currency": "string",
            "payment_amount": "number",
            "payment_reference": "string",
            "purpose_of_payment": "Purpose of Payment",
            "reason_for_trade": "string",
            "russian_central_bank_account": "string",
            "swift_code": "string",
            "trade_type": "string",
            "value_date": "string",
            "vo": "string"
        }
    ],
    "trade_details": [
        {
            "buy_amount": "number",
            "buy_currency": "string",
            "client_rate": "number",
            "client_rate_symbol": "string",
            "inverse_rate": "number",
            "inverse_rate_symbol": "string",
            "sell_amount": "number",
            "sell_currency": "string",
            "value_date": "string"
        }
    ]
}

The response will vary depending on whether accept_partial was set to true and all the requested payments were created successfully.

If all the payments were created, you will receive a 201 Created response.

If some of the payments were created, you will receive a 202 Accepted response.

Both response bodies share a similar model.

Fields

Name	Description
`multipayment_id` Always	The multipayment ID
`account_details` Always	The account to which payments should be sent to fund a trade
`account_details.account_number` Always	The account number
`account_details.bank_identifier` Always	The bank identifier
`account_details.bank_identifier_type` Always	The bank identifier type (UK sort code, US ABA/FedWire, etc.)
`account_details.iban`	The account IBAN
`account_details.swift_code`	The account SWIFT code
`invalid_payments`	A list of payments that were not created, using the same model as the request
`trade_details` Always	The trade details
`trade_details.buy_currency` Always	Buy currency code
`trade_details.buy_amount` Always	Buy amount
`trade_details.client_rate` Always	Trade rate
`trade_details.client_rate_symbol` Always	The symbol of the rate
`trade_details.sell_currency` Always	Sell currency code
`trade_details.sell_amount` Always	Sell amount
`trade_details.inverse_rate` Always	The inverse rate
`trade_details.inverse_rate_symbol` Always	The symbol of the inverse rate
`trade_details.value_date` Always	Value date

Accept a multi payment

PATCH /multipayments/$multipayment_id?client_id=$client_id HTTP/1.1
Authorization: string

Content-Type: application/json

Accepts the trades generated during the multi payment initiation and also books the associated payments.

Request Headers

Header	Description
`Content-Type` Required	`application/json`

Path Parameters

Parameter	Description
`multipayment_id` Required	The multi payment ID

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "account_number": "string",
    "bank_identifier": "string",
    "bank_identifier_type": "string",
    "iban": "string",
    "swift_code": "string"
}

A successful request will return a 200 OK response with the following response body.

Fields

Name	Description
`account_number` Always	The account number
`bank_identifier` Always	The bank identifier
`bank_identifier_type` Always	The bank identifier type (UK sort code, US ABA/FedWire, etc.)
`iban`	The account IBAN
`swift_code`	The account SWIFT code

Reject a multi payment

DELETE /multipayments/$multipayment_id?client_id=$client_id HTTP/1.1
Authorization: string

Rejects the trades generated during the multi payment initiation and also cancels the associated payments.

Path Parameters

Parameter	Description
`multipayment_id` Required	The multi payment ID

Query Parameters

Parameter	Description
`client_id` Required	The ID of the client

Response

HTTP/1.1 204 No Content

A successful request will return a 204 No Content response with an empty response body.

Multipayment models

NewMultiPaymentItem

Every payment instruction to be submitted.

Fields

Name	Description
`account_number` Required	Account number
`bank_address` Required	The bank address of the beneficiary
`bank_code` Required	The bank code of the beneficiary (UK sort code, US ABA/FedWire, etc.)
`bank_country` Required	The bank country of the beneficiary in ISO 3166-1 format (two character alpha code)
`bank_name` Required	Name of the bank account holder
`beneficiary_address`^*	The beneficiary address (deprecated)*
`beneficiary_street_name`^*	The street name of the beneficiary.
`beneficiary_building_number`^*	The building number of the beneficiary.
`beneficiary_floor`^*	The floor of the beneficiary.
`beneficiary_apartment_office_number`^*	The apartment/office number of the beneficiary.
`beneficiary_city`^* Required	The city of the beneficiary.
`beneficiary_state_region`^*	The state/region of the beneficiary.
`beneficiary_post_code`^*	The postcode of the beneficiary.
`beneficiary_country` Required	The beneficiary country in ISO 3166-1 format (two character alpha code)
`beneficiary_name` Required	The beneficiary name
`beneficiary_reference`	Permanent reference to add to a beneficiary for all future payments.
`direction` Required	Acceptable values: buy sell
`iban` Required
`inn`	Unique Taxpayer Personal Identification Number for legal entities registered in Russia.
`kio`	Tax ID for foreign legal entities in Russia.
`payment_currency` Required	Buy currency code
`payment_amount` Required	number
`payment_reference` Required	Payment reference
`purpose_of_payment`	The purpose of payment is mandatory when the beneficiary account has specific currency types. See the section PurposeOfPayment for the currencies and their acceptable values.
`reason_for_trade` Required	Reason for trade. See ReasonForTradeValues for acceptable values.
`russian_central_bank_account`	20-digit code for Russian banks.
`swift_code` Required
`trade_type` Required	Type of trade. Acceptable values: spot
`value_date` Required	Date of the payment
`vo`	Code of currency transaction established by the Central Bank of Russia to describe the purpose of the payment.

* This field and the related rule becomes operational from October 2024. Further communication will follow over emails. Please note, it does not apply to Ebury Mass Payments customers in Production.

Webhook notifications

Practically speaking, a webhook is a POST request to a url of your choice, triggered by an internal event of a remote service. The benefit of webhooks is to receive desired type of notifications to your systems from remote services without regular polling.

The Ebury Events System Webhooks API allows you to add your subscriptions (i.e. HTTP endpoints) to receive Events Systems' notifications.

Usage

# 1. GraphQL query

{
    subscriptions {
        nodes {
            clientId
            contactId
        }
    }
}


# 2. Corresponding HTTP request

POST /webhooks/graphql HTTP/1.1
Authorization: Bearer $access_token
Content-Type: application/json
X-Client-ID: $client_id

{
  "query": "{ subscriptions { nodes { clientId contactId } } }"
  "variables": {}
}

The Webhooks API is using GraphQL.

This means that your queries will look like this:

in GraphQL (example #1)
as an HTTP POST request (example #2)

Your already existing infrastructure can be used to send HTTP requests as usual, and the response will be serialized as JSON data. In addition, detailed data schema information is also provided, helpful to improve tooling on your side.

Notification History

Every notification attempt is stored on our side. On top of the notification details, we also store the status code, headers and body returned by your subscription in response.

Notifications history, including failed attempts will be available for you to review anytime.

Authentication

Authentication is managed as usual for Ebury API services. You have to provide Authorization: Bearer $access_token as described in the Authentication chapter.

Please note that the client_id parameter is still mandatory. However it could be provided in two different ways.

as a query parameter (as usual)
as an X-Client-ID HTTP header field

We are allowing for this second option in order to be more respectful with the GraphQL standards (see: Webhooks Examples).

GraphQL: differences from REST

You can think of the Webhooks API as any traditional (REST) API. However having said that, if you want to make use of a better user experience you may want to consider the following resources:

The Webhooks API is following the GraphQL specs
Each endpoint supports Schema Introspection. This allows you to validate your queries, determine the type of result data, etc.
Pagination goes according to the Relay Cursors Connections Specification. (Consistent pagination and ordering via cursors.)

The Webhooks API has one single endpoint (/webhooks/graphql), supporting uniquely POST requests. Due to this reason, interacting with the API is a bit different from what you may be used to.

(The Webhooks Examples section should help you to get used to required payloads.)

Retrieving information

{
  "query": "{\n    clientId\n    contactId\n}",
  "variables": {}
}

Instead of GET queries, now we will have to send a POST request when aiming to retrieve information.

The JSON payload requires two fields

query: the query as a string
variables (optional): further information to be passed with the request, as a JSON dictionary.

Add/modify/delete

{
  "query": "mutation deleteSubscription($id: UUID!){deleteSubscription(input: {id: $id }) {}}",
  "variables": {
    "id": "c9f8f293-3391-4cc7-9a97-cb0e26d901e9"
  }
}

GraphQL allows for data modifications via internal objects called mutations, referring to GraphQL functions on the Webhooks API database.

A number of mutation functions belong to each data structure, one for each data manipulation action (create, update, delete).

Your HTTP request has to refer to the one specific to your needs. The JSON payload will require

query field
- embedding the mutation function signature
  - embedding the mutation function data
variables: potential variables

Error Reporting

The returned HTTP response may (or may not) contain an error entry. This is a non-empty list of errors, thus only shipped when errors were encountered.

Each entry in the errors list is a map, containing a message string field. Please note that the message is intended for the developer. (see GraphQL Errors Specification).

Great developer tools

Note: This feature is not yet fully available in the initial Webhooks API release. However you may find it useful despite the limited functionality.

As a part of the Webhooks API, an interactive GraphiQL interface is available (at the Webhooks API url root), which facilitates the construction of request payloads enormously.

It allows you to write and execute your queries live, get a description of functionalities available for the schema (with detailed help messages on each), provides embedded text completion for writing syntactically valid queries etc.

Especially in case you are new to GraphQL we strongly recommend you to take a look at this feature. It allows for an easy and natural introduction to the GraphQL syntax. It is extremely helpful, intuitive, self-explaining... and fun.

Securing your webhooks

Ebury will put a signature in every HTTP request sent so you can verify if you can trust the payload. The header X-Ebury-Signature will contain the sha3 HMAC hexdigest of the URL concatenated with the body payload. The secret to be used as key in the HMAC computation can be stored and retrieved alongside other fields of the subscription. If you don't set a secret, the empty string will be used as a key.

For an url url, body body and a secret secret, you can expect a header X-Ebury-Signature to be exactly sha3-256=52cecc9451d6279c3ef1d345c76edb320782203f876d19396fc9baeafbcbf81f.

Webhooks Traceability

To simplify the developer experience, a contact can subscribe several clients to the same url. If this is the case, you will need that the webhook receiver can identify which client is the stakeholder of a particular call. You can do that by checking the value of the header X-Ebury-Client-Id.

Webhooks Types

Ebury supports several types of events, which you can see in the table below. You can subscribe to one specific event or to all of them. In every webhook POST call, you will receive a JSON payload as body. You can identify which type of notification you are receiving, by checking the X-Ebury-Webhook header.

Query all types

You can get a list of all currently supported types by using the custom function webhookTypes.

{
    webhookTypes
}

POST /webhooks/graphql HTTP/1.1
Authorization: Bearer $access_token
Content-Type: application/json
X-Client-ID: $client_id

{
  "query": "{\n    webhookTypes\n}",
  "variables": {}
}

HTTP/1.1 200 OK
Server: nginx/1.13.10
Date: Thu, 10 Sep 2020 19:03:27 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 196
Connection: close
X-GraphQL-Event-Stream: /graphql/stream

{
  "data": {
    "webhookTypes": [
      "TRADE_STATUS_CHANGE",
      "PAYMENT_STATUS_CHANGE",
      "CREDIT_INCOMING_TRANSACTION",
      "CREDIT_MARGIN_TRANSACTION",
      "CREDIT_PAYMENT_RETURNED_TRANSACTION",
      "CREDIT_TRANSACTION",
      "DEBIT_TRANSACTION",
      "ONBOARDING_STATUS_CHANGE"
    ]
  }
}

List of types

This is the current (growing) list of notifications you can receive using the Webhooks API.

Notification	`X-Ebury-Webhook`	Type
Status change on Trades created by the client.	`TradeStatusChange`	TRADE_STATUS_CHANGE
Status change on Payments created by the client.	`PaymentStatusChange`	PAYMENT_STATUS_CHANGE
Incoming funds into client's account.	`CreditIncomingTransaction`	CREDIT_INCOMING_TRANSACTION
Margin credited back into client's account.	`CreditMarginTransaction`	CREDIT_MARGIN_TRANSACTION
Returns of the payments the client initiated.	`CreditPaymentReturnedTransaction`	CREDIT_PAYMENT_RETURNED_TRANSACTION
Credit is made to a client's account.	`CreditTransaction`	CREDIT_TRANSACTION
Debit is made to a client's account.	`DebitTransaction`	DEBIT_TRANSACTION
Status change when onboarding new client	`OnboardingStatusChange`	ONBOARDING_STATUS_CHANGE

TradeStatusChange

{
    "data":
    [
      {
        "beneficiaries": [],
        "rate_symbol": "EURGBP",
        "trade_id": "EBPOTR002781",
        "buy_currency": "EUR",
        "fee_amount": 0.0,
        "parent_trade_id": null,
        "status": "Created",
        "trade_receipt": "/documents?type=tr&id=EBPOTR002781&client_id=EBPCLI00004",
        "rate": 0.935057,
        "order_date": "2020-06-29",
        "maturity_date": "2020-06-29T20:00:00.00Z",
        "sell_currency": "GBP",
        "reference": "",
        "fee_currency": "GBP",
        "synthetic": false,
        "sell_amount": 935.06,
        "trade_type": "spot",
        "buy_amount": 1000.0
      }
    ]
}

This model is a representation of the webhook for a status change on a trade.

Fields

Name	Description
`data` Always	A list of BookedTrade

PaymentStatusChange

{
    "data":
    [
      {
        "account_number": "",
        "amount": 6.02,
        "authorisation_workflow": "4-eyes",
        "authorised_by": null,
        "authorised_date": null,
        "bank_identifier": "",
        "beneficiary_name": "Homer Simpsons S.L.",
        "cancelled_by": null,
        "cancelled_date": null,
        "contact_id": "EBPCON00005",
        "created_date": "2020-07-14",
        "fee_amount": 12.85,
        "fee_currency": "EUR",
        "iban": "GB81KMWJ48036895317360",
        "invoice_required": false,
        "payment_currency": "GBP",
        "payment_date": "2020-07-15",
        "payment_id": "PI02488",
        "payment_instruction": "/documents?type=pi&id=PI02488&client_id=EBPCLI00004",
        "payment_receipt": "/documents?type=pr&id=PI02488&client_id=EBPCLI00004",
        "reference": "Development services",
        "rejected_by": null,
        "rejected_date": null,
        "status": "Validating beneficiary information",
        "swift_code": "GBGBGBGB",
        "trade_id": "EBPOTR002772"
      },
    ],
    "payment_webhook_status": ["CREATED"]
}

This model is a representation of the webhook for a status change for a payment.

Fields

Name	Description
`data` Always	A list of Payment
`payment_webhook_status` Always	A list of PaymentWebhookStatus

CreditTransaction

{
    "data":
    [
        {
          "account_id": "c18a42df-6652-d462-351b-0485a6d6bc16",
          "additional_transaction_information": "EURGBP 0.876804 - other",
          "amount": {
              "amount": "100.00",
              "currency": "EUR"
          },
          "balance": {
              "amount": {
                  "amount": "50212.85",
                  "currency": "EUR"
              },
              "type": "InterimAvailable",
              "credit_debit_indicator": "Credit"
          },
          "booking_datetime": "2019-11-11T20:37:30.598",
          "credit_debit_indicator": "Credit",
          "status": "Booked",
          "transaction_id": "3ae5b450-1e1a-b116-1fde-3cb4f0353e16",
          "transaction_information": "Bought EUR EBPOTR002772",
          "transaction_reference": "EBPOTR002772",
          "value_datetime": "2019-11-11T20:37:30.598",
          "creditor_name": "Jorge Chapa",
          "creditor_account": {
              "account_name": "EBURY OFFICE ACC CHF",
              "account_number": "",
              "bank_identifier": "",
              "bank_identifier_code": "",
              "iban": "GB78BARC12345678901234",
              "swift": ""
          },
          "debtor_name": "Jorge Corp",
          "debtor_account": {
              "account_name": "Cool Account",
              "account_number": "1234567890",
              "bank_identifier": "123456",
              "bank_identifier_code": "",
              "iban": "",
              "swift": "RACZHUH1123"
          }
        }
    ]
}

This model is a representation of the webhook for a credit transaction.

Fields

Name	Description
`data` Always	A list of Transaction

Payment Webhook Status

Status of the payment's webhook

Values

Value	Description
`CREATED`	Payment has been created.
`PENDING_OF_AUTHORIZATION`	Payment is waiting for authorization.
`AUTHORIZED`	Payment has been authorized.
`REJECTED`	Payment has been rejected.
`CANCELLED`	Payment has been cancelled.
`SENT`	Payment instruction sent to payment scheme.
`PENDING_RETURN`	Payment is pending return.
`RETURNED`	Payment has been returned.
`INVALIDATED`	Payment has been invalidated.

OnboardingStatusChange

Will give notification about the change of status during onboarding a client. Example of onboarding message is on a side, more information about onboarding can be found on onboarding documentation

{
  "data": [
    {
      "type": "onboardingRequest",
      "links": {
        "self": "/provision/v2/onboarding/0013N00000CAZrWQAX"
      },
      "id": "0013N00000CAZrWQAX",
      "attributes": {
        "OnboardingStatus": "Client Onboarded",
        "AccountNumber": "455053",
        "EburyId": "ECECLI455053",
        "BecameClient": "2020-04-01"
      }
    }
  ]
}

Webhook Examples

Scenarios presented in this section should be considered as examples. Feel free to modify them to better fit your needs.

Most of the examples will only contain the GraphQL query. As explained earlier, this becomes the string value of the query field in the HTTP POST request payload .

When you create your subscription you should specify which type of notification you are interested in. You can always change it by patching the subscription.

As a reminder, the first example includes both the query and the related HTTP request.

Create a subscription

mutation {
    createSubscription(input: {
        subscription: {
            active: true
            secret: "secret"
            url: "https://httpbin.org/post"
            types: [TRADE_STATUS_CHANGE]
        }
    }) {
        subscription {
            id
        }
    }
}

POST /webhooks/graphql HTTP/1.1
Authorization: Bearer $access_token
Content-Type: application/json
X-Client-ID: $client_id

{
  "query": "mutation createSubscription{\n    createSubscription(\n        input: {\n            active: true\n             secret: \"secret\"\n             url: \"https://httpbin.org/post\"\n       types: [TRADE_STATUS_CHANGE]\n       }\n    ) {\n        subscription {\n            id\n        }\n    }\n}",
  "variables": {}
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 94
Connection: close
Date: Mon, 13 Apr 2020 11:19:09 GMT

{
  "data": {
    "createSubscription": {
      "subscription": {
        "id": "c7677669-8dd6-4deb-923c-c38eb6b65789"
      }
    }
  }
}

In order to receive notifications, the first step is to create a subscription.

Make sure to only include active: true in the payload if you want to receive notifications right after creation. Otherwise you can enable the subscription later.

Once a subscription is active, notifications related to the client will be sent to the specified URL.

Note that the secret is optional and will be used as a key to sign the payload.

Note that the types must be present and will specify which type of notification you want to receive. If you are not sure which types of notification you want to receive you can specify all of them and update them later on by patching the subscription.

As mentioned earlier, we will have to use a so-called mutation. The corresponding GraphQL function is createSubscription, requiring subscription URL and status as parameters.

GraphQL query (example snippet #1)
The query embedded into a HTTP request payload (example #2)
The HTTP response object (example #3)

Ping a subscription

POST /webhooks/ping/c7677669-8dd6-4deb-923c-c38eb6b65789 HTTP/1.1
Authorization: Bearer $access_token
Content-Type: application/json
X-Client-ID: $client_id

HTTP/1.1 204 No Content

If you need to check the connectivity of a subscription, even if it is disabled, you can send a ping event. To do that, you only need to POST, with all the usual headers, the path /webhooks/ping/:subscription_id:. This endpoint does not require a body as input and neither does it return anything: it is only a POST call that will generate a 204 response. Calling the endpoint will generate a ping event to simulate the workflow of a regular webhook, triggering a notification for the configured URL.

The Ping webhook is a special one since it is sent to specific subscriptions. You can expect the communication between this API and your webhook receiver to follow the same rules as other types of webhooks. The header X-Ebury-Client-Id will be populated, and X-Ebury-Webhook will contain the special value Ping. The payload will be a valid json without any specific schema, apart from being signed in X-Ebury-Signature as usual.

Get the list of subscriptions

{
    subscriptions {
        totalCount
        nodes {
            id
            createdAt
            url
            active
            types
        }
    }
}

{
    subscriptions(filter: {
        active: {
            equalTo: true
        }
    }) {
        totalCount
        nodes {
            id
            createdAt
            url
            active
            types
        }
    }
}

Two example usages, to

query the list of all subscriptions (example #1),
or filter only for the active ones (example #2),

Delete a subscription

mutation deleteSubscription($id: UUID!){
    deleteSubscription(
        input: {
            id: $id
        }
    ) {
        subscription {
            id
        }
    }
}

{
    "id": "c9f8f293-3391-4cc7-9a97-cb0e26d901e9"
}

POST /webhooks/graphql HTTP/1.1
Authorization: Bearer $access_token
Content-Type: application/json
X-Client-ID: $client_id

{
  "query": "mutation deleteSubscription($id: UUID!){\n    deleteSubscription(\n        input: {\n            id: $id\n        }\n    ) {\n        subscription {\n            id\n        }\n    }\n}",
  "variables": {
    "id": "c9f8f293-3391-4cc7-9a97-cb0e26d901e9"
  }
}

To delete a subscription you will need to send a mutation object, invoking the deleteSubscription GraphQL function.

In this example, we create a query with an input variable, and then we send the value of the variable.

To make it easier to follow, we include

GraphQL query and internal variable definition (example #1a + #1b)
HTTP request with all embedded in the payload (example #2)

Enable a subscription

mutation enableSubscription($id: UUID!){
    updateSubscription(
        input: {
            id: $id
            patch: {
                active: true
            }
        }
    ) {
        subscription {
            id
            active
        }
    }
}

{
    "id": "c9f8f293-3391-4cc7-9a97-cb0e26d901e9"
}

If you want to change the status (active property) of a subscription, you need to apply a mutation invoking the updateSubscription GraphQL function.

Disable a subscription

mutation disableSubscription($id: UUID!){
    updateSubscription(
        input: {
            id: $id
            patch: {
                active: false
            }
        }
    ) {
        subscription {
            id
            active
        }
    }
}

{
    "id": "c9f8f293-3391-4cc7-9a97-cb0e26d901e9"
}

Disabling a subscription goes just the same.

Get the last notification of every subscription

{
    subscriptions {
        nodes {
            active
            createdAt
            id
            url
            types
            notifications(first:1, orderBy:CREATED_AT_DESC) {
                totalCount
                nodes {
                    id
                    createdAt
                    body
                    attempts {
                        totalCount
                    }
                }
            }
        }
    }
}

The power of GraphQL relies on the ability to navigate across data relationships.

This will allow us to efficiently retrieve a list of subscriptions, with the latest notification belonging to each.

Note that we are using a combination of two options to get the latest notification.

orderBy attribute making sure that the first notification attempt is the newest
first: 1: to get no more but the first (one) notification attempt

Patch a subscription

Patching a subscription is a useful way to change the scope of your notification by changing the types of event you are interested in. When you are not sure which types of events are important for you, you can subscribe for all and then unsubscribe undesired events by patching your subscription. When changing the types, you need to specify the whole new list of types.

Few examples of patching your type values:

types: [] subscribe to none types of events, will have similar effect like disable the subscription by setting Active to False.
types: [TRADE_STATUS_CHANGE, PAYMENT_STATUS_CHANGE, CREDIT_INCOMING_TRANSACTION, CREDIT_MARGIN_TRANSACTION, CREDIT_PAYMENT_RETURNED_TRANSACTION, ONBOARDING_STATUS_CHANGE, CREDIT_TRANSACTION, DEBIT_TRANSACTION] subscribe to all types of events
types: [TRADE_STATUS_CHANGE, CREDIT_INCOMING_TRANSACTION]] subscription to only 2 events type

mutation updateSubscription($id: UUID!, $url: String!, $types: [WebhookType!]){
    updateSubscription(
        input: {
            id: $id
            patch: {
                url: $url
                types: $types
            }
        }
    ) {
        subscription {
            id
            url
            active
            types
        }
    }
}

{
    "id": "ad1e5009-2a8e-44c9-922f-b7da22f66325",
    "url": "https://example.com/",
    "types": ["TRADE_STATUS_CHANGE", "CREDIT_INCOMING_TRANSACTION"]
}

If you want to change the url and event types of a subscription, you need to update it as such:

Responses

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 94
Connection: close
Date: Mon, 13 Apr 2020 11:19:09 GMT

{
  "data": {
    "createSubscription": {
      "subscription": {
        "id": "c7677669-8dd6-4deb-923c-c38eb6b65789"
      }
    }
  }
}

Success

A successful request will return a 200 OK response with a map.

This map will include an entry with

a data field
- that will further include the requested operation
  - that will further include fields that were requested for the response.

Failure

See Error Reporting for details of unsuccessful requests.