NAV Navbar
cURL Python 3

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 to how and where to deploy your application, and we provide the means to integrate foreign exchange functionality 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:

URL Environment Purpose
https://sandbox.ebury.io Sandbox Sandbox API endpoint
https://auth-sandbox.ebury.io Sandbox Sandbox authentication endpoint
https://api.ebury.io Production Live API endpoint
https://auth.ebury.io Production Live authentication endpoint

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:

Rate limiting

Rate limiting of the Ebury API is primarily on a per-client basis — or more accurately described, per user API key. If you get status code 429, it means that you have sent too many requests.

Error Handling

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

ErrorMessage

{
    "code": "string",
    "message": "string",
    "details": "string"
}
Name Type Description
code string A short code for the error
message *  string The error message
details *  string 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.

OpenID flow overview

Authentication Request

Example request to Authorization Server

curl "https://auth.ebury.io/authenticate?\
scope=openid&response_type=code&client_id=[Your API Key]&state=[Your state token]\
&redirect_uri=[Your valid redirect URL]"
from urllib3 import PoolManager
from uuid import uuid4

CLIENT_ID = '[Your state token]'
REDIRECT_URI = '[Your valid redirect URL]'
manager = PoolManager()
response = manager.request('GET',
    'https://auth.ebury.io/authenticate?scope=openid&response_type=code&'\
    'client_id=%s&state=%s&redirect_uri=%s' % (CLIENT_ID, uuid4().hex, REDIRECT_URI)
)

To start the authentication process a call needs to be made to our Authorization Server, which identifies 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.

The parameters required to complete the call successfully are shown in the table below.

Parameter Description Value
client_id Your API key Identifies your application to the Authorization Server
scope The OAuth 2.0 scope parameter Must include the value openid. No other values required
response_type The response type required from the Authorization Server Must be set to code
state A value passed to maintain state between request and callbacks. Recommended by the OpenID specification but mandated in our implementation Should be a random, per request value
redirect_uri The redirect URL that is registered for your application This must match the value we hold

Login

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

Login Screen

Once the credentials have been successfully entered a redirect will be returned the URL that is registered for your application. The redirect will include the following parameters:

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

Get Access Token

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=[Your authorization code]&redirect_uri=[Your valid redirect URL]'
from base64 import b64encode
from urllib3 import PoolManager
from urllib.parse import urlencode

CLIENT_ID = '[Your state token]'
CLIENT_SECRET = '[Your client secret]'
credentials = b64encode(bytes('%s:%s' % (CLIENT_ID, CLIENT_SECRET), 'utf-8')).decode('utf-8')

manager = PoolManager()
response = manager.urlopen(
    'POST',
    'https://auth.ebury.io/token',
    body = urlencode({
        'grant_type': 'authorization_code',
        'code': "[Your authorization code]",
        'redirect_uri': "[Your valid redirect URL]"
    }),
    headers = {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Authorization': 'Basic %s' % credentials
    }
)

Response

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

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

The final step is for your application to retrieve an access token that will provide access to the API. The following parameters are passed to the token endpoint

Parameter Description Value
grant_type An OAuth 2.0 grant type This value must be set to authorization_code
code The authorization code Value returned by authorization endpoint. Cached by the token endpoint, expires if not used within 10 minutes of issuance
redirect_uri Your valid redirect URL This must match the value we hold

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

Field Description Value
token_type Describes the Authorization header scheme when making requests with the token Bearer
access_token An OAuth access token that can be used to call the API Random string
refresh_token An OAuth refresh token that can be used to get a new access token when when the last expires Random string (We will generate a new access token from any of the last 10 refresh tokens)
expires_in Expiry period in seconds from time token returned Currently returns 3600 (1 hour) but will be tuned
id_token A signed, base 64 encoded JSON Web Token that provides verification of the identity that authorized the request See example. The token includes the client identifier, which is a required parameter on the majority of API calls. This is discussed in more detail below.

Get Refresh Token

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: Basic bGV0c3ByZXRlbnQ6aXNhdGFuZW5kCg==" \
https://auth.ebury.io/token \
--data 'grant_type=refresh_token&refresh_token=[Your refresh token]&scope=openid'
from base64 import b64encode
from urllib3 import PoolManager
from urllib.parse import urlencode

credentials = b64encode(bytes('%s:%s' % (CLIENT_ID, CLIENT_SECRET), 'utf-8')).decode('utf-8')

manager = PoolManager()
response = manager.urlopen(
    'POST',
    'https://auth.ebury.io/token',
    body = urlencode({
        'grant_type': 'refresh_token',
        'refresh_token': "[Your refresh token]",
        'scope': 'openid'
    }),
    headers = {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Authorization': 'Basic %s' % credentials
    }
)

Your access token will expire according to the value set in the Get Access Token response, but you can automatically get a new access token by using your refresh token at the Token endpoint. Our OpenID Provider conforms to the refresh token mechanism described here, accepting the following parameters:

Field Description Value
grant_type The refresh token grant type refresh_token
refresh_token The refresh token value One of the last 10 refresh tokens, issued within the last month
scope The OpenID scope openid

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

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 -H "x-api-key: [Your API key]" -H "Authorization: Bearer [Your Access Token]" -H "X-Contact-ID: [The Contact ID]" -H "Content-Type: application/json" \
-X POST \
-d '{
        "trade_type": "spot", 
        "buy_currency": "EUR", 
        "amount": 1500.0, 
        "operation": "buy", 
        "sell_currency": "GBP", 
        "value_date": "2016-09-20"
}' \
"https://api.ebury.io/quotes?quote_type=quote&client_id=[The Client ID]"
import json
from urllib3 import PoolManager

manager = PoolManager()
response = manager.urlopen(
    'POST',
    'https://api.ebury.io/quotes?quote_type=quote&client_id=[The Client ID]',
    body = json.dumps({
        'trade_type': 'spot', 
        'buy_currency': 'EUR', 
        'amount': 1500.0, 
        'operation': 'buy', 
        'sell_currency': 'GBP', 
        'value_date': '2016-09-20'
    }),
    headers = {
        'x-api-key': '[Your API key]',
        'Authorization': 'Bearer [Your Access Token]',
        'X-Contact-ID': '[The Contact ID]',
        'Content-Type': 'application/json'
    }
)

Response

{
  "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 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 different between different accounts in our data model. The majority of customers will only have one client identifier, but some may have multiple accounts and thus multiple identifiers. Where a customer has multiple identifiers the correct one will need to be selected by your application prior to making an API call

Book a Trade

curl -H "x-api-key: [Your API key]" -H "Authorization: Bearer [Your Access Token]" -H "X-Contact-ID: [The Contact ID]" -H "Content-Type: application/json" \
-X POST \
-d '{
        "reason": "Travel costs", 
        "trade_type": "spot"
}' \
"https://api.ebury.io/trades?quote_id=[The Quote ID]&client_id=[The Client ID]"
import json
from urllib3 import PoolManager

manager = PoolManager()
response = manager.urlopen(
    'POST',
    'https://api.ebury.io/trades?quote_id=[The Quote ID]&client_id=[The Client ID]',
    body = json.dumps({
        'reason': 'Travel costs', 
        'trade_type': 'spot'
    }),
    headers = {
        'x-api-key': '[Your API key]',
        'Authorization': 'Bearer [Your Access Token]',
        'X-Contact-ID': '[The Contact ID]',
        'Content-Type': 'application/json'
    }
)

Response

{
  "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 -H "x-api-key: [Your API key]" -H "Authorization: Bearer [Your Access Token]" -H "X-Contact-ID: [The Contact ID]" -H "Content-Type: application/json" \
-X POST \
-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",
}' \
"https://api.ebury.io/beneficiaries?client_id=[The Client ID]"
import json
from urllib3 import PoolManager

manager = PoolManager()
response = manager.urlopen(
    'POST',
    'https://api.ebury.io/beneficiaries?client_id=[The Client ID]',
    body = json.dumps({
        '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',
    }),
    headers = {
        'x-api-key': '[Your API key]',
        'Authorization': 'Bearer [Your Access Token]',
        'X-Contact-ID': '[The Contact ID]',
        'Content-Type': 'application/json'
    }
)

Response

{
  "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 -H "x-api-key: [Your API key]" -H "Authorization: Bearer [Your Access Token]" -H "X-Contact-ID: [The Contact ID]" -H "Content-Type: application/json" \
-X POST \
-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
        }
    ]
}' \
"https://api.ebury.io/payments?client_id=[The Client ID]"
import json
from urllib3 import PoolManager

manager = PoolManager()
response = manager.urlopen(
    'POST',
    'https://api.ebury.io/payments?client_id=[The Client ID]',
    body = json.dumps({
        'trade_id': 'EBPOTR999999',
        'payments':[
            {
                'beneficiary_id': 'EBPBEN999999',
                'account_id': '99999',
                'amount': 10.50,
                'payment_date': '2016-10-30',
                'reference': '2016-10-29',
                'email_beneficiary': True
            }
        ]
    }),
    headers = {
        'x-api-key': '[Your API key]',
        'Authorization': 'Bearer [Your Access Token]',
        'X-Contact-ID': '[The Contact ID]',
        'Content-Type': 'application/json'
    }
)

Response

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

Getting Quotes

Get an estimate or firm quote:

Get an estimate or firm quote

POST /quotes HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
Content-Type: application/json

{
    "requestBody": {
        "trade_type": "string",
        "sell_currency": "string",
        "buy_currency": "string",
        "amount": "number",
        "operation": "string",
        "value_date": "string"
    }
}
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"
}
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"
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Get an estimate or firm quote. An estimate is as it's described: * The current rates on offer within the Ebury platform with no firm quote. * A firm quote returns a reference than can be used to book a trade.

Parameters

Name In Type Description
quote_type *  query
Acceptable values:
  • estimate
  • quote
The quote type. A quote_type of quote returns a quote_id which a trade can be booked against
client_id *  query string The ID of the client this quote is for
requestBody *  body QuoteRequest Request Payload
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact
Content-Type *  header string Supports only: application/json

Responses

Http code Type Description
200 EstimateResponse Estimated rates response
201 QuoteResponse Quote created
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Client ID not found
409 ErrorMessage Requested quote causes a conflict, see response body for details
502 ErrorMessage Internal integration error. Contact support

Quote Models

QuoteRequest

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

Fields

Name Type Format Description
trade_type *  string
Acceptable values:
  • spot
  • forward
The trade type
sell_currency *  string Sell currency
buy_currency *  string Buy currency
amount *  number double Amount
operation *  string
Acceptable values:
  • buy
  • sell
Operation (buy or sell)
value_date string date Value date for the trade. If the value date is not valid then the quote will be returned for next available value date. If the value date is not provided, then the quote will be returned for the next available valid value date.

EstimateResponse

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

Fields

Name Type Format Description
estimated_rate *  number double The estimated rate
estimated_rate_symbol *  string The symbol of estimated rate
inverse_rate *  number double Inverse rate
inverse_rate_symbol *  string The symbol of inverse rate
fee_amount *  number float Fee amount
fee_currency *  string Fee currency
value_date *  string date Date on which quote is requested
warning string A warning is only returned if the requested value date was not valid and the next available date has been returned.

QuoteResponse

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

Fields

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

ErrorMessage

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

Fields

Name Type Format Description
message *  string The error message
code string A short code for the error

Making Trades

Create a Trade

POST /trades HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
Content-Type: application/json

{
    "requestBody": {
        "reference": "string",
        "reason": "string"
    }
}
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"
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Initiate a new trade. You need to have an existing quote_id to do this

Parameters

Name In Type Description
quote_id *  query string The identifier of the quote
client_id *  query string The ID of the client
requestBody *  body NewTrade Request Payload
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact
Content-Type *  header string Supports only: application/json

Responses

Http code Type Description
201 ConfirmedTrade Trade created
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Client or quote ID not found
409 ErrorMessage Requested trade causes a conflict that can be corrected, see response body for details
502 ErrorMessage Internal integration error. Contact support

Get all trades

GET /trades HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
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",
        "beneficiaries": [
            "string"
        ],
        "fee_currency": "string",
        "fee_amount": "number",
        "synthetic": "boolean",
        "trade_receipt": "string",
        "reference": "string"
    }
]
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Get all the trades for a given client ID

Parameters

Name In Type Format Description
client_id *  query string The ID of the client
trade_type query array[string] Acceptable values:
  • spot
  • forward
  • window_forward
  • drawdown
  • ndf
Filter the response to include only trades with a matching type.
page query integer int32 The desired page number for pagination. By default is 1.
page_size query integer int32 The number of items per page for pagination. By default is 50.
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact

Responses

Http code Type Description
200 array[BookedTrade] List of trades
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Client or quote ID not found
502 ErrorMessage Internal integration error. Contact support

Get a trade

GET /trades/{trade_id} HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
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",
    "beneficiaries": [
        "string"
    ],
    "fee_currency": "string",
    "fee_amount": "number",
    "trade_receipt": "string",
    "reference": "string",
    "payments": [
        {
            "payment_id": "string",
            "amount": "number",
            "beneficiary_name": "string",
            "payment_instruction": "string",
            "payment_receipt": "string",
            "status": "string",
            "url": "string"
        }
    ]
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Get a trade with a specific trade_id

Parameters

Name In Type Description
trade_id *  path string Trade identifier
client_id *  query string The ID of the client
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact

Responses

Http code Type Description
200 ExtendedBookedTrade Trade exists
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Client or trade ID not found
502 ErrorMessage Internal integration error. Contact support

Trade Models

ErrorMessage

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

Fields

Name Type Format Description
message *  string The error message
code string A short code for the error

NewTrade

{
    "reference": "string",
    "reason": "string"
}

Fields

Name Type Format Description
reason *  string Reason for trade
reference string Reference for the trade.

ConfirmedTrade

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

Fields

Name Type Format Description
trade_id *  string Trade identifier
bank_account *  object An existing bank account
maturity_date *  string date-time Date on or before which funds must be received by Ebury. Date and time are in UTC.
initial_margin_amount number double Only for forwards. Trade's deposit amount
initial_margin_due_date string date-time Only for forwards. Date on or before which deposit must be received by Ebury. Date and time are in UTC.

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",
    "beneficiaries": [
        "string"
    ],
    "fee_currency": "string",
    "fee_amount": "number",
    "synthetic": "boolean",
    "trade_receipt": "string",
    "reference": "string"
}

Fields

Name Type Format Description
trade_id *  string Trade identifier
trade_type *  string Trade type
status *  string Status of the trade
buy_currency *  string Buy currency code
buy_amount *  number float Buy amount
sell_currency *  string Sell currency code
sell_amount *  number float Sell amount
rate *  number float Booked rate
rate_symbol *  string The symbol of booked rate
order_date *  string date Order date
maturity_date *  string date Maturity date
beneficiaries *  array[string] Beneficiary names
fee_currency *  string date Fee currency
fee_amount *  number float Fee amount
synthetic *  boolean Identifies as a synthetic future contracts
trade_receipt string uri The URL to get the trade receipt
reference string Additional trade reference. Example: Invoice number.

ExtendedBookedTrade

{
    "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",
    "beneficiaries": [
        "string"
    ],
    "fee_currency": "string",
    "fee_amount": "number",
    "synthetic": "boolean",
    "trade_receipt": "string",
    "reference": "string"
    "payments": [
        {
            "payment_id": "string",
            "amount": "number",
            "beneficiary_name": "string",
            "payment_instruction": "string",
            "payment_receipt": "string",
            "status": "string",
            "url": "string"
        }
    ]
}

Fields

Name Type Format Description
trade_id *  string Trade identifier
trade_type *  string Trade type
status *  string Status of the trade
buy_currency *  string Buy currency code
buy_amount *  number float Buy amount
sell_currency *  string Sell currency code
sell_amount *  number float Sell amount
rate *  number float Booked rate
rate_symbol *  string The symbol of booked rate
order_date *  string date Order date
maturity_date *  string date Maturity date
beneficiaries *  array[string] Beneficiary names
fee_currency *  string date Fee currency
fee_amount *  number float Fee amount
synthetic *  boolean Identifies as synthetic future contracts
trade_receipt string uri The URL to get the trade receipt
reference string Additional trade reference. Example: Invoice number.
payments array[object] List of payments made on trade

TradeStatus

Status of the trade

Fields

Status 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

Getting Metadata

The Metadata API provides two sources of information that help consumers our APIs:

Get beneficiary metadata

GET /metadata/beneficiary HTTP/1.1
x-api-key: string
Authorization: string
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "country": "string",
        "reason_required": "boolean",
        "currencies": [
            {
                "currency": "string",
                "mandatory_data": [
                    [
                        "string"
                    ]
                ],
                "optional_data": [
                    "string"
                ]
            }
        ]
    }
]
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Beneficiary metadata describes the fields required to provision a valid beneficiary for a given country/currency combination:

Parameters

Name In Type Description
Authorization *  header string The access token
x-api-key *  header string The API key

Responses

Http code Type Description
200 BeneficiaryMetadata Beneficiary metadata
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
502 ErrorMessage Internal integration error. Contact support

Get currency metadata

GET /metadata/currency HTTP/1.1
x-api-key: string
Authorization: string
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"
        }
    }
]
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Describe a currency

Parameters

Name In Type Description
data_only query boolean Optional. Used to generate a flat array (not described in schema as it's impractical)
Authorization *  header string The access token
x-api-key *  header string The API key

Responses

Http code Type Description
200 CurrenciesMetadata Currency metadata
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
502 ErrorMessage Internal integration error. Contact support

Metadata Models

ErrorMessage

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

Fields

Name Type Format Description
message *  string The error message
code string A short code for the error

BeneficiaryMetadata

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

Fields

Name Type Format Description
array[object] Beneficiary metadata

CurrenciesMetadata

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

Fields

Name Type Format Description
array[CurrencyMetadataItem] Currencies metadata

CurrencyMetadataItem

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

Fields

Name Type Format Description
currency string Currency symbol
reason_required boolean Show if reason required for this currency is mandatory
buy CutOff Information of this currency if it is used as "buy" currency
sell CutOff Information of this currency if it is used as "sell" currency
invalid_value_dates InvalidValueDates Invalid trading dates and its reasons

CutOff

    {
        "cutoff_days": "integer",
        "cutoff_time": "string"
    }

Fields

Name Type Format Description
cutoff_days number int32 Cutoff days of the currency
cutoff_time string date-time Cutoff time for the currency in GMT/UTC

InvalidValueDates

    {
        "YYYY-MM-DD": "reason"
    }

Fields

Name Type Format Description
YYYY-MM-DD string date Invalid trading date
reason string Reason of invalid trading date

Managing Beneficiaries

Create a new beneficiary

POST /beneficiaries HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
Content-Type: application/json

{
    "requestBody": {
        "name": "string",
        "email_addresses": [
            "string"
        ],
        "email_notification": "boolean",
        "address_line_1": "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",
        "russian_central_bank_account": "string",
        "swift_code": "string",
        "vo": "string"
    }
}
HTTP/1.1 201 Created
Content-Type: application/json

{
    "name": "string",
    "email_addresses": [
        "string"
    ],
    "email_notification": "boolean",
    "address_line_1": "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"
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

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

Parameters

Name In Type Description
client_id *  query string The ID of the client
requestBody *  body NewBeneficiary Request Payload
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact
Content-Type *  header string Supports only: application/json

Responses

Http code Type Description
201 Beneficiary Beneficiary created
400 ErrorMessage Formatting or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Client ID not found
409 ErrorMessage Request invalid due to beneficiary management rules. Refer to error message for additional details
502 ErrorMessage Internal integration error. Contact support

Get beneficiaries

GET /beneficiaries HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "name": "string",
        "email_addresses": [
            "string"
        ],
        "email_notification": "boolean",
        "address_line_1": "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"
    }
]
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Get all beneficiaries for a given client

Parameters

Name In Type Format Description
client_id *  query string The ID of the client
page query integer int32 The desired page number for pagination. By default is 1.
page_size query integer int32 The number of items per page for pagination. By default is 50.
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact

Responses

Http code Type Description
200 array[Beneficiary] List of beneficiaries
400 ErrorMessage Formatting or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Client ID not found
502 ErrorMessage Internal integration error. Contact support

Get a single beneficiary

GET /beneficiaries/{beneficiary_id} HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "string",
    "email_addresses": [
        "string"
    ],
    "email_notification": "boolean",
    "address_line_1": "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"
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Get a single beneficiary by beneficiary ID

Parameters

Name In Type Description
beneficiary_id *  path string The ID of the beneficiary
client_id *  query string The ID of the client
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact

Responses

Http code Type Description
200 Beneficiary The beneficiary
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Beneficiary or client ID not found
502 ErrorMessage Internal integration error. Contact support

Update a beneficiary

PATCH /beneficiaries/{beneficiary_id} HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
Content-Type: application/json

{
    "requestBody": [
        {
            "name": "string",
            "value": "string"
        }
    ]
}
HTTP/1.1 204 No Content
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Update a single beneficiary by beneficiary ID, using a list of names and values. NB We do not currently support PUT. This may be supported in a later release

Parameters

Name In Type Description
beneficiary_id *  path string
client_id *  query string The ID of the client
requestBody *  body BeneficiaryUpdate List of field names and values for update
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact
Content-Type *  header string Supports only: application/json

Responses

Http code Type Description
204 no content Beneficiary updated
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Beneficiary or client ID not found
409 ErrorMessage Could not update beneficiary due to data constraint or conflict with beneficiary status. Refer to error message for additional details
502 ErrorMessage Internal integration error. Contact support

Delete a beneficiary

DELETE /beneficiaries/{beneficiary_id} HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
HTTP/1.1 204 No Content
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Delete a single beneficiary by beneficiary ID

NB Deletes may fail due to constraints in our backend systems

Parameters

Name In Type Description
beneficiary_id *  path string
client_id *  query string The ID of the client
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact

Responses

Http code Type Description
204 no content Beneficiary deleted
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Beneficiary or client ID not found
502 ErrorMessage Internal integration error. Contact support

Beneficiary Models

ErrorMessage

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

Fields

Name Type Format Description
message *  string The error message
code string A short code for the error

BankAccountData

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

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

Fields

Name Type Format Description
account_number string Account number. Refer to the Metadata API for valid types
bank_address_line_1 string
bank_country_code *  string
bank_currency_code *  string
bank_identifier string
bank_identifier_type string
bank_name string Name of the bank account holder
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

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",
    "reason_for_trade": "string",
    "reference_information": "string",
    "russian_central_bank_account": "string",
    "swift_code": "string",
    "vo": "string",
    "account_id": "integer"
}

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

Fields

Name Type Format Description
account_number string Account number. Refer to the Metadata API for valid types
bank_address_line_1 string
bank_country_code *  string
bank_currency_code *  string
bank_identifier string
bank_identifier_type string
bank_name string Name of the bank account holder
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 int32

BeneficiaryCoreData

{
    "name": "string",
    "email_addresses": [
        "string"
    ],
    "email_notification": "boolean",
    "address_line_1": "string",
    "post_code": "string",
    "country_code": "string"
}

Fields

Name Type Format Description
name *  string
email_addresses array[string]
email_notification *  boolean Whether the beneficiary should receive email notification of payments
address_line_1 string
post_code string
country_code *  string

NewBeneficiary

{
    "name": "string",
    "email_addresses": [
        "string"
    ],
    "email_notification": "boolean",
    "address_line_1": "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",
    "russian_central_bank_account": "string",
    "swift_code": "string",
    "vo": "string"
}

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

Fields

Name Type Format Description
name *  string
email_addresses array[string]
email_notification *  boolean Whether the beneficiary should receive email notification of payments
address_line_1 string
post_code string
country_code *  string
account_number string Account number. Refer to the Metadata API for valid types
bank_address_line_1 string
bank_country_code *  string
bank_currency_code *  string
bank_identifier string
bank_name string Name of the bank account holder
correspondent_account string
correspondent_swift_code string
iban string
inn string Unique Taxpayer Personal Identification Number for legal entities registered in Russia.
kbk string
kio string Tax ID for foreign legal entities in Russia.
kpp string
purpose_of_payment string
Acceptable values:
  • Trade Settlement for Goods /CGODDR/
  • Trade Settlement for Goods - Partial return /CGODDR/PART/
  • Trade Settlement for Goods - Cancellation /CGODDR/RETN/
  • Trade Settlement for Services /CSTRDR/
  • Trade Settlement for Services - Partial return /CSTRDR/PART/
  • Trade Settlement for Services - Cancellation /CSTRDR/RETN/
  • Payment to Current Account /COCADR/
  • Payment to Current Account - Cancellation /COCADR/RTN/
  • Payment to Capital Account /CCTFDR/
  • Payment to Capital Account - Partial return /CCTFDR/PART/
  • Payment to Capital Account - Cancellation /CCTFDR/RETN/
  • Charity Donation /CCDNDR/
  • Charity Donation - Cancellation /CCDNDR/RTN/
The purpose of payment. Required for CNY currency. Only code is sent, eg. /CGODDR/.
reason_for_trade string
reference_information string
russian_central_bank_account string 20-digit code for Russian banks.
swift_code string
vo string Code of currency transaction established by the Central Bank of Russia to describe the purpose of the payment.

BeneficiaryData

{
    "name": "string",
    "email_addresses": [
        "string"
    ],
    "email_notification": "boolean",
    "address_line_1": "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"
        }
    ]
}

Fields

Name Type Format Description
name *  string
email_addresses array[string]
email_notification *  boolean Whether the beneficiary should receive email notification of payments
address_line_1 string
post_code string
country_code *  string
bank_accounts *  array[BankAccount]

Beneficiary

{
    "name": "string",
    "email_addresses": [
        "string"
    ],
    "email_notification": "boolean",
    "address_line_1": "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"
}

Fields

Name Type Format Description
name *  string
email_addresses array[string]
email_notification *  boolean Whether the beneficiary should receive email notification of payments
address_line_1 string
post_code string
country_code *  string
bank_accounts *  array[BankAccount]
beneficiary_id *  string The beneficiary ID
created *  string
aml_status *  string
active *  string

AMLStatus

AML status of the Beneficiary

Fields

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

BeneficiaryUpdate

[
    {
        "name": "string",
        "value": "string"
    }
]

Fields

Name Type Format Description
array[object] List of field names and values for update

Making Payments

The Payments API allows you make payments to a known beneficiary with an existing trade. Your Ebury account can be set up to make payments in one of 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 payment

POST /payments HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
Content-Type: application/json

{
    "requestBody": {
        "trade_id": "string",
        "async": "boolean",
        "payments": [
            {
                "beneficiary_id": "string",
                "account_id": "string",
                "amount": "number",
                "email_beneficiary": "boolean",
                "payment_date": "string",
                "reference": "string"
            }
        ]
    }
}
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",
    }
]
HTTP/1.1 204 No Content
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Create one or more payments with an existing trade_id, beneficiary ID and account ID. Payment processing can be made asynchronous by setting the async flag in the request body.

Parameters

Name In Type Description
client_id *  query string The ID of the client
requestBody *  body NewPayment Request Payload
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact
Content-Type *  header string Supports only: application/json

Responses

Http code Type Description
201 array[NewPaymentItem] Payment(s) created synchronously
204 no content Payment(s) processing started (asynchronously)
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 ErrorMessage Trade, beneficiary or account ID not found. See error message for further details
409 ErrorMessage Payment instruction could not be completed due to issues with input data. See error message for further details. NB if multiple payments were sent all will fail
502 ErrorMessage Internal integration error. Contact support

Search or retrieve payments

GET /payments HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
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",
        "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"
    }
]
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Search or retrieve all payments for a given client ID

Parameters

Name In Type Format Description
client_id *  query string The ID of the client
page query integer int32 The desired page number for pagination. By default is 1.
page_size query integer int32 The number of items per page for pagination. By default is 50.
reference query string Filter payments by reference.
Authorization *  header string The access token
X-Contact-ID *  header string The ID of the contact

Responses

Http code Type Description
200 Payments Client payments
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Client ID not found
502 ErrorMessage Internal integration error. Contact support

Retrieve the payment

GET /payments/{payment_id} HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
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",
    "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"
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Retrieve a payment with a given payment ID

Parameters

Name In Type Description
payment_id *  path string Unique idenifier for payment
client_id *  query string The ID of the client
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact

Responses

Http code Type Description
200 Payment The client payment
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Client or payment ID not found
502 ErrorMessage Internal integration error. Contact support

Authorise or reject a payment

PATCH /payments/{payment_id} HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
Content-Type: application/json
HTTP/1.1 204 No Content
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

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

Note that a different Contact ID to needs to be used to authorise payments

Parameters

Name In Type Description
payment_id *  path string Unique idenifier for payment
client_id *  query string The ID of the client
action *  query string The action to take (authorise or reject)
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact
Content-Type *  header string Supports only: application/json

Responses

Http code Type Description
204 no content Payment successfully authorised or rejected
400 ErrorMessage Formatting or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Payment or client ID not found
502 ErrorMessage Internal integration error. Contact support

Delete a payment

DELETE /payments/{payment_id} HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
HTTP/1.1 204 No Content
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Delete a payment with a given payment ID

Parameters

Name In Type Description
payment_id *  path string Unique idenifier for payment
client_id *  query string The ID of the client
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact

Responses

Http code Type Description
204 no content Payment successfully deleted
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Payment or client ID not found
502 ErrorMessage Internal integration error. Contact support

Payment Models

ErrorMessage

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

Fields

Name Type Format Description
message *  string The error message
code string A short code for the error

NewPayment

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

A list of payments with known beneficiary/bank account IDs.

Fields

Name Type Format Description
trade_id string Unique identifier of the trade the payment is allocated to
async boolean Create the payment(s) asynchronously. Payments are created synchronously by default.
payments array[object] A list of payments

NewPaymentItem

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

Fields

Name Type Format Description
payment_id string The payment identifier
fee_amount number float Fee amount
fee_currency string Fee currency
payment_instruction string uri URI to download payment instruction
payment_receipt string uri URI to download payment receipt
status string The current status of the payment
reference string The payment reference

Payment

{
    "payment_id": "string",
    "contact_id": "string",
    "trade_id": "string",
    "account_number": "string",
    "amount": "number",
    "bank_identifier": "string",
    "beneficiary_name": "string",
    "created_date": "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"
}

Fields

Name Type Format Description
payment_id *  string Unique identifier for the payment
contact_id *  string Unique identifier of the contact who booked the payment
trade_id *  string Unique identifier of the trade the payment is allocated to
account_number string
amount number float Payment amount
bank_identifier string
beneficiary_name string Name of the beneficiary
created_date string date Payment instruction created date
fee_amount number float Fee amount
fee_currency string Fee currency
iban string
payment_currency string Currency the payment was made in
payment_date string date Target payment date
payment_instruction string uri URI to download payment instruction
payment_receipt string uri URI to download payment receipt
status string The current status of the payment
swift_code string
authorised_by string The user who authorised the payment
authorised_date string date The date when payment was authorised
rejected_by string The user who rejected the payment
rejected_date string date The date when payment was rejected
cancelled_by string The user who cancelled the payment
cancelled_date string date The date when payment was cancelled
authorisation_workflow string
Acceptable values:
  • simple
  • 4-eyes
The authorisation workflow of the payment
invoice_required boolean Whether or not the payment requires an invoice
reference string The payment reference

Payments

[
    {
        "payment_id": "string",
        "contact_id": "string",
        "trade_id": "string",
        "account_number": "string",
        "amount": "number",
        "bank_identifier": "string",
        "beneficiary_name": "string",
        "created_date": "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"
    }
]

Fields

Name Type Format Description
array[object] Client payments

Status

Status of the payments

Fields

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

Managing Contacts

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

Get Contacts

GET /contacts HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "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_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"
    }
]
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Get all contacts for a given client

Parameters

Name In Type Description
client_id *  query string The ID of the client
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact

Responses

Http code Type Description
200 array[Contact] List of contacts
400 ErrorMessage Formatting or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Client ID not found
502 ErrorMessage Internal integration error. Contact support

Get a single contact

GET /contacts/{contact_id} HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
HTTP/1.1 200 OK
Content-Type: application/json

{
    "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_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"
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Get a single contact by contact ID

Parameters

Name In Type Description
contact_id *  path string The ID of the contact
client_id *  query string The ID of the client
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact

Responses

Http code Type Description
200 Contact The contact
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Contact or client ID not found
502 ErrorMessage Internal integration error. Contact support

Update a contact

PATCH /contacts/{contact_id} HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
Content-Type: application/json

{
    "requestBody": {
        "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",
    }
}
HTTP/1.1 204 No Content
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Update a single contact identified by contact_id.

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

All other fields will use their default value if omitted.

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

Parameters

Name In Type Description
contact_id *  path string
client_id *  query string The ID of the client
requestBody *  body ContactUpdate List of field names and values for update
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact
Content-Type *  header string Supports only: application/json

Responses

Http code Type Description
204 no content Contact updated
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Contact or client ID not found
409 ErrorMessage Could not update contact due to data constraint or conflict with contact status. Refer to error message for additional details
502 ErrorMessage Internal integration error. Contact support

Contact Models

ErrorMessage

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

Fields

Name Type Format Description
message *  string The error message
code string A short code for the error

ContactData

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

Fields

Name Type Format Description
name string Full name of the contact
email_address *  string email Email address/username of the contact
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 as ISO 3166 two-character code
country_name string Full name of the country
post_code string
password_reset_required boolean

ContactUpdateableData

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

}

Fields

Name Type Format Default Description
language string Language expressed as ISO 639-1 two-character code
locale string Locale expressed as ISO 639-1 two-character code
time_zone string
has_online_access boolean false Contact has access to Ebury Online
can_authorise_payments boolean false Contact can authorise payments
can_make_same_currency_payments boolean false Contact can create trades and assign same currency payments
can_manage_beneficiaries boolean false Contact can manage beneficiaries
can_manage_beneficiaries_groups boolean false Contact can manage beneficiaries groups
can_manage_contacts boolean false Contact can manage contacts
can_manage_fix_forwards boolean false Contact can manage fixed forwards
can_manage_multipayments boolean false Contact can manage multipayments
can_manage_payments boolean false Contact can manage payments
can_manage_permissions boolean false Contact can manage permissions
can_trade boolean false Contact can execute trades

Contact

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

Fields

Name Type Format Description
name string Full name of the contact
email_address *  string email Email address/username of the contact
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 as ISO 3166 two-character code
country_name string Full name of the country
post_code string
password_reset_required boolean
language string Language expressed as ISO 639-1 two-character code
locale string Locale expressed as ISO 639-1 two-character code
time_zone string
has_online_access boolean Contact has access to Ebury Online
can_authorise_payments boolean Contact can authorise payments
can_make_same_currency_payments boolean Contact can create trades and assign same currency payments
can_manage_beneficiaries boolean Contact can manage beneficiaries
can_manage_beneficiaries_groups boolean Contact can manage beneficiaries groups
can_manage_contacts boolean Contact can manage contacts
can_manage_fix_forwards boolean Contact can manage fixed forwards
can_manage_multipayments boolean Contact can manage multipayments
can_manage_payments boolean Contact can manage payments
can_manage_permissions boolean Contact can manage permissions
can_trade boolean Contact can execute trades
contact_id string 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",
}

Fields

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

Viewing Documents

Get a document

GET /documents HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
HTTP/1.1 200 OK
Content-Type: text/plain

"string"
HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: text/plain

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 502 Bad Gateway
Content-Type: text/plain

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

Get a documents for a given client

Parameters

Name In Type Description
type *  query
Acceptable values:
  • pi (payment instruction)
  • pr (payment receipt)
  • tr (trade receipt)
The document type
id *  query string The ID of the entity that generated this document e.g. payment, trade, etc.
client_id *  query string The ID of the client
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact

Responses

Http code Type Description
200 string Base 64 encoded document content
400 ErrorMessage Formatting or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Document or client ID not found
502 ErrorMessage Internal integration error. Contact support

Document Models

ErrorMessage

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

Fields

Name Type Format Description
message *  string The error message
code string A short code for the error

Executing Multipayments

Create a multi payment instruction

POST /multipayments HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
Content-Type: application/json

{
    "requestBody": [
        {
            "account_number": "string",
            "bank_address": "string",
            "bank_code": "string",
            "bank_country": "string",
            "bank_name": "string",
            "beneficiary_address": "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"
       }
    ]
}
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_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"
        }
    ]
}
HTTP/1.1 202 Accepted
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_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"
        }
    ]
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 409 Conflict
Content-Type: application/json

[
    {
        "account_number": "string",
        "bank_address": "string",
        "bank_code": "string",
        "bank_country": "string",
        "bank_name": "string",
        "beneficiary_address": "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": "string",
        "reason_for_trade": "string",
        "russian_central_bank_account": "string",
        "swift_code": "string",
        "trade_type": "string",
        "value_date": "string",
        "vo": "string"
    }
]
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

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

Parameters

Name In Type Description
client_id *  query string The ID of the client
trade_id query string Optional. Trade ID to book payments against. Omit if trade should be executed to fund payments
sell_currency query string Optional. If trade_id omitted, a sell currency must be supplied
accept_partial query boolean Optional. Accept a partially successful instruction. If true, send successful instructions for payment. If false, reject the entire instruction. By default this parameter is set to false.
accept_immediately *  query boolean Mandatory, set to 'true'. Accept the quote immediately, do not require confirmation.
requestBody *  body NewMultiPayment Request Payload
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact
Content-Type *  header string Supports only: application/json

Responses

Http code Type Description
201 MultiPaymentResponse Multi payment created, see response body for status
202 MultiPaymentResponse Multi payment accepted with errors, see response body for status
400 ErrorMessage Formatting or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Client ID not found
409 MultiPaymentErrorMessage All payments invalid or partial instruction not allowed, see response body for details
502 ErrorMessage Internal integration error. Contact support

Accept a multi payment

PATCH /multipayments/{multipayment_id} HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json

{
    "account_number": "string",
    "bank_identifier": "string",
    "bank_identifier_type": "string",
    "iban": "string",
    "swift_code": "string"
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 409 Conflict
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Accept a multi payment generated trade and book in payments

Parameters

Name In Type Description
multipayment_id *  path string The multi payment ID
client_id *  query string The ID of the client
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact
Content-Type *  header string Supports only: application/json

Responses

Http code Type Description
200 BankAccount Multi payment accepted and payments booked (pending back office operations)
400 ErrorMessage Formatting or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Multi payment or client ID not found
409 no content Multi payment already accepted or rejected
502 ErrorMessage Internal integration error. Contact support

Rejects a multi payment

DELETE /multipayments/{multipayment_id} HTTP/1.1
x-api-key: string
Authorization: string
X-Contact-ID: string
HTTP/1.1 204 No Content
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "string",
    "code": "string"
}
HTTP/1.1 404 Not Found
HTTP/1.1 409 Conflict
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

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

Rejects a multi payment trade and cancels the payments

Parameters

Name In Type Description
multipayment_id *  path string The multi payment ID
client_id *  query string The ID of the client
Authorization *  header string The access token
x-api-key *  header string The API key
X-Contact-ID *  header string The ID of the contact

Responses

Http code Type Description
204 no content Multi payment rejected
400 ErrorMessage Formatting, parameter or schema validation error. See error message for further details
401 no content Access denied due to authentication failure
403 ErrorMessage Could not complete action due to data constraints. Refer to error message for additional details
404 no content Multi payment or client ID not found
409 no content Multi payment already rejected
502 ErrorMessage Internal integration error. Contact support

Multipayment Models

ErrorMessage

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

Fields

Name Type Format Description
message *  string The error message
code string A short code for the error

BankAccount

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

The account to which payments should be sent to fund a trade

Fields

Name Type Format Description
account_number string
bank_identifier string
bank_identifier_type string The bank identifier type (UK sort code, US ABA/FedWire, etc.)
iban string
swift_code string

NewPayment

{
    "account_number": "string",
    "bank_address": "string",
    "bank_code": "string",
    "bank_country": "string",
    "bank_name": "string",
    "beneficiary_address": "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": "string",
    "reason_for_trade": "string",
    "russian_central_bank_account": "string",
    "swift_code": "string",
    "trade_type": "string",
    "value_date": "string",
    "vo": "string"
}

A new payment instruction. Where you have no value for a given field set it but leave empty (see example)

Fields

Name Type Format Description
account_number *  string Account number
bank_address *  string The bank address of the beneficiary
bank_code *  string The bank code of the beneficiary (UK sort code, US ABA/FedWire, etc.)
bank_country *  string The bank country of the beneficiary in ISO 3166-1 format (two character alpha code)
bank_name *  string Name of the bank account holder
beneficiary_address *  string The beneficiary address
beneficiary_name *  string The beneficiary name
beneficiary_country *  string The beneficiary country in ISO 3166-1 format (two character alpha code)
beneficiary_reference string Permanent reference to add to a beneficiary for all future payments.
direction *  string
Acceptable values:
  • buy
  • sell
iban *  string
inn string Unique Taxpayer Personal Identification Number for legal entities registered in Russia.
kio string Tax ID for foreign legal entities in Russia.
payment_currency *  string Buy currency code
payment_amount *  number float Buy amount
payment_reference *  string Payment reference
purpose_of_payment string
Acceptable values:
  • Trade Settlement for Goods /CGODDR/
  • Trade Settlement for Goods - Partial return /CGODDR/PART/
  • Trade Settlement for Goods - Cancellation /CGODDR/RETN/
  • Trade Settlement for Services /CSTRDR/
  • Trade Settlement for Services - Partial return /CSTRDR/PART/
  • Trade Settlement for Services - Cancellation /CSTRDR/RETN/
  • Payment to Current Account /COCADR/
  • Payment to Current Account - Cancellation /COCADR/RTN/
  • Payment to Capital Account /CCTFDR/
  • Payment to Capital Account - Partial return /CCTFDR/PART/
  • Payment to Capital Account - Cancellation /CCTFDR/RETN/
  • Charity Donation /CCDNDR/
  • Charity Donation - Cancellation /CCDNDR/RTN/
The purpose of payment. Required for CNY currency. Only code is sent, eg. /CGODDR/.
reason_for_trade *  string Reason for trade
russian_central_bank_account string 20-digit code for Russian banks.
swift_code *  string
trade_type string
Acceptable values:
  • spot
value_date *  string Date of the payment
vo string Code of currency transaction established by the Central Bank of Russia to describe the purpose of the payment.

NewMultiPayment

[
    {
        "account_number": "string",
        "bank_address": "string",
        "bank_code": "string",
        "bank_country": "string",
        "bank_name": "string",
        "beneficiary_address": "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": "string",
        "reason_for_trade": "string",
        "russian_central_bank_account": "string",
        "swift_code": "string",
        "trade_type": "string",
        "value_date": "string",
        "vo": "string"
    }
]

Fields

Name Type Format Description
array[NewPayment] New multi payment data

MultiPaymentError

{
    "account_number": "string",
    "bank_address": "string",
    "bank_code": "string",
    "bank_country": "string",
    "bank_name": "string",
    "beneficiary_address": "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": "string",
    "reason_for_trade": "string",
    "russian_central_bank_account": "string",
    "swift_code": "string",
    "trade_type": "string",
    "value_date": "string",
    "vo": "string"
}

A new payment instruction. Where you have no value for a given field set it but leave empty (see example)

Fields

Name Type Format Description
account_number *  string Account number
bank_address *  string The bank address of the beneficiary
bank_code *  string The bank code of the beneficiary (UK sort code, US ABA/FedWire, etc.)
bank_country *  string The bank country of the beneficiary in ISO 3166-1 format (two character alpha code)
bank_name *  string Name of the bank account holder
beneficiary_address *  string The beneficiary address
beneficiary_name *  string The beneficiary name
beneficiary_country *  string The beneficiary country in ISO 3166-1 format (two character alpha code)
beneficiary_reference string Permanent reference to add to a beneficiary for all future payments.
direction *  string
Acceptable values:
  • buy
  • sell
iban *  string
inn number Unique Taxpayer Personal Identification Number for legal entities registered in Russia.
kio string Tax ID for foreign legal entities in Russia.
payment_currency *  string Buy currency code
payment_amount *  number float Buy amount
payment_reference *  string Payment reference
purpose_of_payment string
Acceptable values:
  • Trade Settlement for Goods /CGODDR/
  • Trade Settlement for Goods - Partial return /CGODDR/PART/
  • Trade Settlement for Goods - Cancellation /CGODDR/RETN/
  • Trade Settlement for Services /CSTRDR/
  • Trade Settlement for Services - Partial return /CSTRDR/PART/
  • Trade Settlement for Services - Cancellation /CSTRDR/RETN/
  • Payment to Current Account /COCADR/
  • Payment to Current Account - Cancellation /COCADR/RTN/
  • Payment to Capital Account /CCTFDR/
  • Payment to Capital Account - Partial return /CCTFDR/PART/
  • Payment to Capital Account - Cancellation /CCTFDR/RETN/
  • Charity Donation /CCDNDR/
  • Charity Donation - Cancellation /CCDNDR/RTN/
The purpose of payment. Required for CNY currency. Only code is sent, eg. /CGODDR/.
reason_for_trade *  string Reason for trade
russian_central_bank_account string 20-digit code for Russian banks.
swift_code *  string
trade_type string
Acceptable values:
  • spot
value_date *  string Date of the payment
vo string Code of currency transaction established by the Central Bank of Russia to describe the purpose of the payment.

MultiPaymentErrorMessage

[
    {
        "account_number": "string",
        "bank_address": "string",
        "bank_code": "string",
        "bank_country": "string",
        "bank_name": "string",
        "beneficiary_address": "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": "string",
        "reason_for_trade": "string",
        "russian_central_bank_account": "string",
        "swift_code": "string",
        "trade_type": "string",
        "value_date": "string",
        "vo": "string"
    }
]

Fields

Name Type Format Description
array[MultiPaymentError] Multi payment error data

MultiPaymentResponse

{
    "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_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": "string",
            "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"
        }
    ]
}

Fields

Name | Type | Format | Description multipayment_id *  | integer | int32 | The multipayment ID account_details | object | | The account to which payments should be sent to fund a trade invalid_payments | array[MultiPaymentError] | | trade_details | array[object] | |

Terms of Use

This API License Agreement (the “Agreement”), effective as of the date of acceptance of this Agreement (the “Effective Date”), is between Ebury Partners UK Limited. (“Ebury”) and you, or the individual, company or other entity that you represent (“Licensee”).

The Licensee represents and warrant that: (i) they have the necessary power and authority to enter into this Agreement, and that the performance of your obligations will not constitute a breach or otherwise violate any other Agreement or the rights of any third party arising therefrom; (ii) you will maintain, throughout the Term, all required rights and licenses related to the Licensee Applications and the Licensee Applications shall not infringe or otherwise violate any third party rights, including but not limited to third party intellectual property rights; and (iii) your uses of the Licensed Materials do and shall comply with all applicable domestic, foreign, federal, state and local laws, rules, and regulations.

Ebury reserves the right to update and change, from time to time, the Ebury API Policies (including these Terms of Use, the Guidelines, and all documents incorporated by reference). The most recent version of these Terms of Use are available at the Developer Portal. Ebury may change these Terms of Use by posting a new version without notice to you. Use of the Ebury API after such change constitutes acceptance of such changes.

Definitions:

API Key means the confidential information supplied by Ebury to an Licensee that uniquely identifies the Licensee’s software application and allows it to access the Ebury API.

Application(s) means the Licensee’s software.

Application Credentials means the confidential information supplied by Ebury that allows the Licensee’s software application(s) to access the API. Collectively this information comprises an API key, OAuth Client ID and OAuth Client Secret.

API Documents means the documentation, data and information provided by Ebury regarding the use oft he API through the Developer Portal.

Client means a customer of the Licensee who uses the Licensee’s software application to access the Ebury services offered by the Ebury API.

Confidential Information means all confidential information, in whatever form (including written or oral), disclosed by one party to the other, including but not limited to, financial, marketing and personnel information, techniques, processes, trade secrets, know-how, designs, methodologies, schematics, ideas, analyses, statistics, performance information, user documentation, internal documentation, details of planned or current products or services, customer or supplier details, financial records, payment details, transaction data, Licensee Information, computer records or software, specifications, APIs, models, prototypes, compositions, samples, Application Credentials, User Credentials, or other information that is or may be either applicable to or related in any way to the business or affairs of such party or which is marked confidential or secret

Developer Portal means a secure website provided by Ebury that gives Licensees personal the means to generate and access the Application Credentials that give them access to the API.

Ebury means Ebury Partners UK Limited, a private limited company registered in England and Wales with registered number 7088713 whose registered office is at 42-44 Grosvenor Gardens, London, SW1W 0EB.

Ebury API means the API developed by Ebury and offered to Licensees for the purpose of accessing Ebury services.

Ebury Policies means the Terms of Use, the Guidelines, Privacy Policy and Cookie Policy

Effective Date means ______ 2016

OAuth Client ID means the confidential information supplied by Ebury that, together with other Application Credentials allows the Licensee’s software application to authenticate Clients in order to use the Ebury API.

Oauth Client Secret means the confidential information supplied by Ebury that, together with other Application Credentials allows the Licensee’s software application to authenticate Clients in order to use the Ebury API.

User Credentials means means the confidential information supplied by Ebury that is used by the Licensee’s Clients to access the profile and transactional data of their user account on Ebury’s backend systems via the API. This information comprises a username and password.

  1. The Ebury API is owned by Ebury and are licensed to you on a worldwide (except as limited below), non-exclusive, non-sublicenseable, revocable basis on the terms and conditions set forth herein, subject to the Ebury API Policies These Terms of Use define legal use of the Ebury API, all updates, revisions, substitutions, and any copies of the Ebury API made by or for you. All rights not expressly granted to you are reserved by Ebury.
  2. This Agreement shall commence on the Effective Date and will remain in effect until terminated pursuant to this clause. Subject to the restrictions set forth in these Terms of Use, the Licensee may use the Ebury API and any updates provided by Ebury (in its sole discretion). Either party may terminate this Agreement by written notice at any time, for any reason, or for no reason including, but not limited to, the Licensee’s violation of any provision of this Agreement. Any termination of this Agreement shall also terminate the licenses granted hereunder. Upon termination of this Agreement for any reason, the Licensee will stop using, and either return to Ebury, or destroy and remove from all computers, hard drives, networks, and other storage media, all copies of the Licensed Materials and any Confidential Information in your possession, and shall certify to Ebury that such actions have occurred
  3. The following provisions of the Terms of Use regarding data collection, storage, use, ownership disclaimer of any warranty, limitation of liability, hold harmless and indemnity and general terms survive any termination of the Agreement.
  4. Any communication or content submitted by you to Ebury is subject to these Terms of Use and the Terms of Service.
  5. The Licensee shall not use the Ebury API for any purpose that violates any law or regulation, any right of any person, including but not limited to intellectual property rights, rights of privacy, or rights of personality, or in any manner inconsistent with the Ebury API Policies.
  6. The Licensee shall not sell, lease, share, transfer, or sublicense the Ebury API or access or access codes thereto or derive income from the use or provision of the Ebury API whether for direct commercial or monetary gain or otherwise, unless the Ebury API Policies specifically permit otherwise or Ebury gives prior, express, written permission.
  7. In a prominent location in all Licensee Applications, the Licensee shall indicate that the application has been created using the Ebury API and API Documents.
  8. The Licensee shall not use the Ebury API in a manner that exceed Rate Limits, constitutes excessive or abusive usage, or otherwise fails to comply or is inconsistent with any part of the Ebury API Policies, to be determined by Ebury in their sole discretion.
  9. The Licensee shall not use the Ebury API in a product or service that competes with products or services offered by Ebury unless the Ebury API Policies specifically permit otherwise or Ebury gives prior, express, written permission during or as part of the contract negotiations.
  10. The Licensee must be reachable at all times for any security questions or concerns Ebury may have. If the contact details for the Licensee change Ebury must be notified immediately.
  11. The Licensee must ensure that all materials, including software and documents, that form part of the Licensee's Application must be checked with generally accepted Internet industry standard up-to-date antivirus and anti-worm software, and determined to be virus-free and worm-free. Any data provided to the Ebury API must not contain harmful scripts or code.
  12. The Licensee must ensure that the networks, operating system and software of its web server(s), routers, databases, and computer systems (collectively, “System” or “Systems”) must be properly configured to generally accepted Internet industry standards, as required to securely operate your Application.
  13. The Licensee must promptly report any security deficiencies in or intrusions to their Systems that you discover by writing via email to security@ebury.com. You will work with Ebury and anyone third party Ebury designate to immediately correct any security deficiency, and will disconnect immediately any intrusions or intruder. In the event of any such security deficiency or intrusion, you will make no public statements (i.e. press, blogs, bulletin boards, etc.) without prior written and express permission from Ebury in each instance.
  14. The Licensee will minimise access to and use of the User Credentials. Wherever possible, the Licensee should log (with time and date) use of the User Credentials to enable a complete audit trail of activities. When an individual terminates his or her employment with you, his or her passwords and access password facilities must be terminated immediately.
  15. Ebury will have the right, at its own expense, to review, or to have an independent third party that is not your competitor, to inspect and review your compliance with these security provisions. You will (at your own expense) correct any security flaws detected by such a review as soon as possible. You will then promptly certify to Ebury in writing that the security flaw has been corrected, along with a description of the corrective action(s) taken. Ebury will give you 48 hours notice before conducting such a review, and may conduct no more than four reviews annually. Any such review will be conducted during regular business hours in such a manner as not to interfere with normal business activities. If a review reveals a material breach of any of these security provisions, you will reimburse Ebury for the reasonable costs of the review.
  16. The Licensee may not retain or use, and must immediately remove from any Application and any data repository in their possession or under their control any Ebury user data obtained through the Ebury API not explicitly identified as being storable indefinitely in the API documents within 24 hours after the time at which you obtained the data.
  17. The Licensee may not disclose any Ebury user data or store any Ebury user data in any data repository which enables any third party access unless such disclosure or third party access is expressly permitted by Ebury.
  18. The Licensee may from time to time, gain access to Confidential Information. You may use Confidential Information only to the extent necessary to exercise your rights under this Agreement. You may not disclose Confidential Information to a third party without the prior express consent of Ebury, provided in writing or by email. You agree that you will protect Confidential Information from unauthorised use, access, or disclosure in the same manner that you would use to protect its own confidential and proprietary information of a similar nature and in any event with no less than a reasonable degree of care.
  19. The Ebury API may be protected by copyrights, trademarks, service marks, international treaties, and/or other proprietary rights and laws of England and Wales and other countries. Ebury rights apply to the Ebury API and all output and executables of the Ebury API, excluding any software components developed by you which do not themselves incorporate the Ebury API or any output or executables of the Ebury API. You agree to abide by all applicable proprietary rights laws and other laws, as well as any additional copyright notices or restrictions contained in the Ebury API Policies. Ebury owns all rights, title, and interest in and to the Ebury API. These Terms of Use grant you no right, title, or interest in any intellectual property owned or licensed by Ebury, including (but not limited to) the Ebury API and Ebury trademarks.
  20. Ebury may elect to provide you with support or modifications (“Support”) for the Ebury API in its sole discretion, and may terminate such support at any time without notice to you. Ebury may change, suspend, or discontinue any aspect of the Ebury API at any time, including the availability of the Ebury API. Ebury may also impose limits on certain features and services or restrict your access to parts or the Ebury API without notice or liability.
  21. Ebury reserves the right to charge fees for future use of or access to the Ebury API or the in Ebury's sole discretion. If Ebury decides to charge for use or access, Ebury will provide you prior notice of such charges.
  22. Ebury does not provide representation or warranty, express or implied as to the use of the Ebury API including, but not limited to any implied warranty of merchantability, accuracy, results of use, reliability, fitness for a particular purpose, availability, security, title and / or non-infringement. Ebury further disclaims any warranty that the use of the Ebury API will be uninterrupted, error-free, virus free or secure. Use of the Ebury API is at the discretion and risk of the Licensee and the Licensee is solely responsible for any damage that results from the use of the Ebury API including, but not limited to, any damage to the Licensee’s computer system or loss of data.
  23. Ebury shall not, under any circumstances, be liable for any indirect, incidental, consequential, special or exemplary damages arising out of or in connect with the use of the Ebury API, whether based on breach of contract, breach of warranty, tort (including negligence, product liability or otherwise), or any other pecuniary loss to the maximum extent permitted by applicable law.
  24. To the maximum extent permitted by applicable law, you hereby release and waive all claims against Ebury, and its subsidiaries, affiliates, officers, agents, licensors, co-branders or other partners, and employees from any and all liability for claims, damages (actual and/or consequential), costs and expenses (including litigation costs and attorneys' fees) of every kind and nature, arising from or in any way related to your use of Ebury API’s. You understand that any fact relating to any matter covered by this release may be found to be other than now believed to be true and you accept and assume the risk of such possible differences in fact. In addition, you expressly waive and relinquish any and all rights and benefits which you may have under any other state or federal statute or common law principle of similar effect, to the fullest extent permitted by law.
  25. To the maximum extent permitted by applicable law, you agree to hold harmless and indemnify Ebury and its subsidiaries, affiliates, officers, agents, licensors, co-branders or other partners, and employees from and against all claims, damages, losses, liabilities, actions, judgments, costs, and expenses brought by a third party arising out of or in connection with: (i) any act or omission by you in connection with your use of the Ebury API; (ii) your use of the Ebury API, including but not limited to other than as expressly allowed by this Agreement; (iii) the Licensee’s breach of this Agreement, including but not limited to your representations and warranties herein; or (iv) any Licensee Application.
  26. The Licensee is required to make any claim arising out of this Agreement within one (1) year of the claim arising.
  27. Notwithstanding any provision hereof, for all purposes of the Terms of Use, Ebury and the Licensee shall be and act independently and not as partner, joint venturer, agent, employee or employer of the other. You shall not have any authority to assume or create any obligation for or on behalf of Ebury, express or implied, and you shall not attempt to bind Ebury to any contract.
  28. If any provision of the Terms of Use is found by a court of competent jurisdiction to be invalid, the parties nevertheless agree that the court should endeavor to give effect to the parties' intentions as reflected in the provision and the other provisions of such documents remain in full force and effect.
  29. The Ebury API Policies and the relationship between the Licensee and Ebury shall be governed by the exclusively by the laws of England and Wales and the parties submit to the exclusive jurisdiction of the courts of England and Wales.
  30. Ebury's failure to exercise or enforce any right or provision of the Terms of Use shall not constitute a waiver of such right or provision.
  31. Ebury shall not be deemed to be in default of any provisions of this Agreement or be liable for any delay, failure in performance, or interruption of service resulting directly or indirectly from acts of God, civil or military authority, civil disturbance, war, terrorism, strikes, fires, other catastrophes, power off telecommunications failure or any other cause beyond its reasonable control.
  32. A person who is not a party to this Agreement shall not have any rights under, or in connection with, it by virtue of the Contracts (Rights of Third Parties) Act 1999 to enforce any term of this Agreement.
  33. The Licensee shall not assign this Agreement nor any rights or obligations in this Agreement without Ebury’s written consent, not to be unreasonably withheld. If Ebury provides its written consent to any assignment of this Agreement, this Agreement shall be binding upon the successors, heirs, and assigns of the Licensee.
  34. This Agreement may be executed in one or more counterparts. Signatures may be exchanged by fax, or scanned copies sent by email, with original signatures to follow. Each party to this Agreement agrees that it will be bound by its own faxed or scanned signature and that it accepts the faxed or scanned signatures of the other parties to this Agreement.
  35. The Terms of Use constitute part of Ebury API Policies which constitute the entire agreement between Ebury and the Licensee with respect to the subject matter hereof.