NAV Navbar
shell python go php

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:

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:

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:

Credentials

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

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:

  1. Redirect the user to Ebury to authorise your app
  2. The user authenticates with Ebury
  3. If 2FA is enabled, the user provides the verification code on the 2FA screen
  4. Ebury redirects the user back to your app with an authorization code
  5. 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.

Login Screen

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:

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.

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:

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:

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

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 Max Length 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:

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.

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:

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:

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.

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:

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

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.


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

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.


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

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

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.

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

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. (Coming soon)
page-size
The number of items per page for pagination. Default value is 50. (Coming soon)
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. (Coming soon)
page-size
The number of items per page for pagination. Default value is 50. (Coming soon)
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. (Coming soon)
page-size
The number of items per page for pagination. Default value is 50. (Coming soon)
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.

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.

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

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:

  1. in GraphQL (example #1)
  2. 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.

  1. as a query parameter (as usual)
  2. 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 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

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

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.

  1. GraphQL query (example snippet #1)
  2. The query embedded into a HTTP request payload (example #2)
  3. 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

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

  1. GraphQL query and internal variable definition (example #1a + #1b)
  2. 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.

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:

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

Failure

See Error Reporting for details of unsuccessful requests.