Introduction
The Ebury API helps you fund and manage your international business by making trading and payments easy to integrate into your applications. You choose how and where to deploy your application, and we provide the means to integrate foreign exchange and payment functionalities in them directly. The API is modular, with the following core areas of functionality:
- Quotes: Get live rates, either estimated or a short-lived quote that you can use to book a trade;
- Trades: Use a quote to execute a trade;
- Payments: Use a trade to fund payments;
- Multi Payments: Wraps trades, beneficiary management and payments into a "bulk" operation, allowing payments initiation across a number of currencies;
- Account Management: Profile updates, beneficiary management, etc.
In terms of style, the API is a "pragmatic" REST + JSON API with a design approach aimed at simplicity and ease of use. A few notes:
- URIs do not descend more that one i.e. /quotes, /trades, etc.;
- We use links where it makes sense to convey information to our API consumers but we are not religious about full-on HATEOAS/code-on-demand style. If links help we use them;
- We will version our API on major versions only, with the version number defined in the hostname , e.g. https://api-v1.ebury.io/trades;
- We'll be looking to add support for Webhooks once our first production release is GA.
Getting Started
The Ebury API has been designed for ease of use, but there are a number of things that need to happen or you need to know before you can start developing against it.
Onboarding
In order to use the API your company needs to be one of the following:
- To be an existing Ebury customer with access to Ebury Online;
- To be on-boarded as an Ebury customer with access to Ebury Online: Currently this is an out-of-band process that needs to be completed by the Ebury sales team.
Credentials
With an active Ebury Online account you need a few details to call the API:
- A client secret that is used in the Authentication workflow described below;
- An access token which you will get by implementing the Authentication workflow;
- A client account identifier that links a user to a given account and needs to be passed to the Authentication workflow;
- You'll need to supply a redirect URL, which will be used during the Authentication workflow.
Environments
The following is a list of environments available when developing against or using our API:
Environment Endpoints
URL | Purpose |
---|---|
https://sandbox.ebury.io |
Sandbox API endpoint |
https://auth-sandbox.ebury.io |
Sandbox authentication endpoint |
https://api.ebury.io |
Production API endpoint |
https://auth.ebury.io |
Production authentication endpoint |
https://trustedsandbox.ebury.io |
mTLS Sandbox (both authentication and API) |
https://trusted.ebury.io |
mTLS Production (both authentication and API) |
API Description
Whilst each subject area is documented below they are also supported by an individual Swagger specification document. Please use the links below to download for your desired environment:
Environment | JSON | YAML |
---|---|---|
Sandbox |
https://sandbox.ebury.io/openapi.json | https://sandbox.ebury.io/openapi.yaml |
Production |
https://api.ebury.io/openapi.json | https://api.ebury.io/openapi.yaml |
Rate limiting
Rate limiting of the Ebury API is primarily on a per-client basis. If you receive a response with a status code of 429 Too Many Requests
, it means that you have been rate limited for sending too many requests, and should wait before sending further requests.
Error Handling
The Ebury API tries to honour HTTP return codes relevant to the error that is being conveyed. However, 4xx HTTP return codes are also used as a "blanket" with more information to be found in the response body of the error message e.g., a 409
will indicate an issue with the data sent that can be rectified: you should consult this message to help you take corrective action.
Idempotency
The Ebury API is not exposing idempotent operations by default.
The POST
requests can however include a header X-Idempotency-Id
, to be used as a lock to gain idempotency features.
After every POST
request, the response header X-Idempotency-Status
is returned with the result of the idempotency logic.
This is an opt-in feature. If the header X-Idempotency-Id
is not present, no extra logic is considered.
The first time the API sees a X-Idempotency-Id
, it returns accepted
and locks the value for 15 days.
The following times the same value is used within the first 15 days: the API will return duplicated
, with status 409
, and will not process the request.
We suggest using a random UUID as X-Idempotency-Id
.
Summary for situations.
Request method | X-Idempotency-Id |
Response status | X-Idempotency-Status |
Meaning |
---|---|---|---|---|
No POST |
Not checked | As usual | Not present | No extra logic |
POST |
Not present | As usual | missing |
No extra logic |
POST |
Present, first time seen | As usual | accepted |
Lock acquired for 1 day |
POST |
Present, already seen in last day | 409 | duplicated |
Lock was already acquired, this request was already accepted |
POST |
Present, but the system cannot check it | 503 | unavailable |
The intention was acknowledged, but the service cannot check for the idempotency |
HTTP Response Codes
Response code | Meaning |
---|---|
200 OK |
Request completed successfully. See individual endpoints for details of response content. |
201 Created |
Request completed successfully, and a resource was created. See individual endpoints for details of response content. |
202 Accepted |
Request completed successfully, but not completely processed. See individual endpoints for details of response content. |
400 Bad Request |
The request could not be processed due to some error e.g., formatting, parameter or schema validation. See error message for details of response content. |
401 Unauthorized |
Access denied due to authentication failure |
403 Forbidden |
Could not complete action due to data constraints. See error message for details of response content. |
404 Not Found |
The requested resource could not be found. See individual endpoints for details of how to identify resources. |
409 Conflict |
Request could not be completed. See error message for details of response content. |
429 Too Many Requests |
You have exceeded the rate limit for IP or server. See rate limiting for details. |
502 Bad Gateway |
Internal error. See error message for details of response content. |
503 Service Unavailable |
Internal error. See error message for details of response content. |
504 Gateway Timeout |
Internal timeout. See error message for details of response content. |
Error Message
{
"code": "string",
"message": "string",
"details": "string"
}
Error messages are presented as JSON objects.
Error Message Fields
Field | Description |
---|---|
code |
A short code for the error |
message |
The error message |
details |
Error details |
Authentication
The Ebury authentication scheme is based on OpenID Connect 1.0, which builds on OAuth 2.0 to make it easier to verify the identity of end users. We've chosen OpenID Connect as we believe it offers our consumers a good mix of security and flexibility and implemented that Authorization Code flow for OpenID Connect: The steps required to complete this flow are detailed in the following sections.
The diagram below shows an overview of the process when Second Factor Authentication (2FA) is disabled:
When 2FA in enabled the process is slightly different as can be seen on the following diagram:
Acquire an access token
Acquiring an access token is a three-step process:
- Redirect the user to Ebury to authorise your app
- The user authenticates with Ebury
- If 2FA is enabled, the user provides the verification code on the 2FA screen
- Ebury redirects the user back to your app with an authorization code
- Exchange the authorization code for an access token
Redirect the user to Ebury
"https://auth.ebury.io/authenticate?
scope=openid&
response_type=code&
client_id=$client_id&
state=$state&
redirect_uri=$redirect_uri"
To start the authentication process a request needs to be made in a browser to our authorization server to identify the application attempting to access the user's profile. This may be implemented in a mobile or web application but the access tokens can be used for server-based applications as well.
Query Parameters
Parameter | Description |
---|---|
client_id Required |
Your client identifier |
scope Required |
Must be openid ; no other values are supported |
response_type Required |
Must be code |
state Required |
A random, per request value used to maintain state between request and callbacks and protect against cross-site request forgery attacks |
redirect_uri Required |
The redirect URL that is registered for your application, this must match the value we hold |
User Authentication
If all parameters are successfully validated the Authorization Server will present an Ebury login screen. The user will be required to enter their Ebury Online email address and password, as shown below.
Ebury redirects back to your app
HTTP/1.1 302 Found
Location: https://your.redirect.url/?code=$authorization_code&state=$state_token
Once the credentials have been successfully entered, one of two things can happen:
- If the user does not have Second Factor Authentication (2FA) enabled, the authentication process is completed (Authentication completed)
- If the user has 2FA enabled, go to Second Factor Authentication
Second Factor Authentication
If the user has 2FA enabled, it will be redirected to the 2FA screen and will be issued a 2FA code (SMS/TOTP are supported for now). The user will be required to enter this code, as shown below:
If the verification code was entered correctly then the authentication process is completed (Authentication completed)
Query Parameters
Parameter | Description |
---|---|
code Required |
Value returned by authorization endpoint |
client_id Required |
Your client identifier |
Authentication completed
After the authentication process is completed, the user will be redirected to the redirect_uri
registered for the application. The following querystring parameters will be included:
Response Parameters
Parameter | Description |
---|---|
code |
A code that allows your application to call the Token Endpoint to complete the OpenID flow |
state |
Value passed from your application in the original authorization request |
Exchange the authorization code
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic bGV0c3ByZXRlbnQ6aXNhdGFuZW5kCg==" \
https://auth.ebury.io/token \
--data 'grant_type=authorization_code&code=$code&redirect_uri=$redirect_uri'
Response
{
"token_type": "Bearer",
"access_token": "XKtOK3hNzKpLkaom3J2MEPyKm7f7jZ",
"refresh_token": "2E9KVBXgVzQSPTvoHjJB1Eu2eBjzup",
"expires_in": 3600,
"id_token": "eyJhbGciOiAiSFMyNTYifQ==.ewogICJhdWQiOiAiWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFgiLAogICJzdWIiOiAiWFhYWFhYWFhYWFgiLAogICJpc3MiOiAiaHR0cHM6Ly9hdXRoLmVidXJ5LmlvIiwKICAiaWF0IjogIjE0NjQyNjY2MzkiLAogICJjbGllbnRzIjogWwogICAgIlhYWFhYWFhYWFhYIgogIF0sCiAgImV4cCI6ICIxNDY0MzUzMDM5Igp9Cg==.bkieHxES1spJnVmDmhganElaP6LZfikKXZ8uphVQwUo"
}
The final step is for your application to exchange the authorisation code for an access token that will provide access to the API. This must happen within 10 minutes of receiving your authorisation code. The following parameters are passed to the token endpoint
Query Parameters
Parameter | Description |
---|---|
grant_type Required |
Must be set to authorization_code |
code Required |
Value returned by authorization endpoint |
redirect_uri Required |
The redirect URL that is registered for your application, this must match the value we hold |
If the all parameters are correct a response will be returned containing the following:
Response Fields
Field | Description |
---|---|
token_type |
The Authorization header scheme to use when making requests, will be Bearer |
access_token |
An OAuth access token that can be used to call the API |
refresh_token |
An OAuth refresh token that can be used to get a new access token when when the last expires |
expires_in |
Expiry period in seconds from time token returned, currently returns 3600 (1 hour) |
id_token |
A signed, base 64 encoded JSON Web Token that provides verification of the identity that authorized the request. The token includes the client identifier, which is a required parameter on the majority of API calls. |
Decoded JSON Web Token (without signature)
{
"alg": "HS256"
}
{
"aud": "XXXXXXXXXXXXXXXXXXXXXXXXXX",
"sub": "XXXXXXXXXXX",
"iss": "https://auth.ebury.io",
"iat": "1464266639",
"clients": [{
"client_id": "XXXXXXXXXXX",
"client_name": "Example client name"
}],
"exp": "1464353039"
}
Sample code for extracting data from the JSON Web Token
var jsonData = JSON.parse(responseBody);
token = jsonData["access_token"];
postman.setEnvironmentVariable("token", token);
idtoken = parseJwt(jsonData["id_token"]);
postman.setEnvironmentVariable("contact_id", idtoken["sub"]);
clients = idtoken["clients"];
postman.setEnvironmentVariable("client_id", clients[0].client_id);
/*function to decode JSON web token*/
function parseJwt(token) {
var base64Url = token.split(".")[1];
var base64 = base64Url.replace("-", "+").replace("_", "/");
return JSON.parse(atob(base64));
}
By decoding this token we can get the value for client_id
needed for future requests.
An array of client_id
and client_name
lists the potential clients that the contact can act on behalf of. The majority of customers will only have one client identifier, but some may have multiple client accounts and thus multiple identifiers that the contact can act on
The client_id
is required in query params of requests post authentication in order to identify the client to which the request is on behalf of. Your application may have to allow a contact to select the correct client_id
to use.
Refreshing access
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic $access_token" \
https://auth.ebury.io/token \
--data 'grant_type=refresh_token&refresh_token=$refresh_token&scope=openid'
Your access token will expire according to the value set in the Exchange the authorisation code response, but you can directly get a new access token by using your refresh token without needing to restart the authentication from the start. Our OpenID Provider conforms to the refresh token mechanism described here. The refresh token lifespan is configurable depending on the client's needs.
Request Fields
Field | Description |
---|---|
grant_type Required |
Should be refresh_token |
refresh_token Required |
One of the last 10 refresh tokens, issued within the last 'n' days. Where 'n' is the refresh token lifespan agreed with the client (default value is 28 days). |
scope Required |
Should be openid |
If successful, the response will contain the same data as the original access token response.
Getting an access token on behalf of a client
It is possible for financial institutions to get an access token on behalf of their clients by using the contact id of the client.
This functionality is not available per default, you need to contact Ebury to enable it for each contact you need an access token for.
This endpoint is only available using mTLS.
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic $access_token" \
https://trusted.ebury.io/token/$contact_id \
--data 'grant_type=client_credentials'
--cert fullchain.pem \
--key privkey.pem
Path Parameters
Parameter | Description |
---|---|
contact_id Required |
The contact identifier |
Request Fields
Field | Description |
---|---|
grant_type Required |
Should be client_credentials |
If successful, the response will contain the access token response.
Authenticating requests
GET /example-endpoint HTTP/1.1
Authorization: Bearer your-access-token
All requests must be authenticated with an access token.
Almost all requests will accept an optional Ebury user identifier, set in the X-Contact-Id
header.
Request Headers
Header | Description |
---|---|
Authorization Required |
Your access token, prefixed with the Bearer scheme |
x-api-key |
Your API key (Deprecated) |
X-Contact-Id Optional |
Identifier for an Ebury user (Deprecated) |
Trusted authentication
By default when a client connects to a server over HTTPS only the identity of the server is verified.
Ebury supports verifying the identity of the client as well by using a client certificate.
To use this functionality you need to connect using these URLs instead of the ones you usually use.
Environment | Hostname |
---|---|
Sandbox |
https://trustedsandbox.ebury.io |
Production |
https://trusted.ebury.io |
Also, note that you will use these endpoints for both authentication and API access. For example:
- To retrieve an access token in the sandbox environment you would call https://trustedsandbox.ebury.io/token instead of https://auth.ebury.io/token
- To create a payment in the sandbox environment you would call https://trustedsandbox.ebury.io/payments instead of https://api.ebury.io/payments
In order to use this functionality you need to provide Ebury with the subject distinguished name of the certificate you will be using to connect because we will match the subject DN you provide with the subject DN of the client's certificate used during the connection.
In order to check the validity of the client certificate you will be using to connect to and also to get the Subject DN of your certificate you can use the check_cert
endpoint.
curl --cert fullchain.pem --key privkey.pem https://trustedsandbox.ebury.io/cert_check
package main
import (
"crypto/tls"
"io/ioutil"
"net/http"
"log"
"strings"
)
func main() {
cert, err := tls.LoadX509KeyPair("fullchain.pem",
"privkey.pem")
if err != nil {
log.Fatal(err)
}
tlsConfig := &tls.Config{
Certificates: []tls.Certificate{cert},
MinVersion: tls.VersionTLS13,
}
tlsConfig.BuildNameToCertificate()
transport := &http.Transport{TLSClientConfig: tlsConfig}
req, err := http.NewRequest("GET", "https://trustedsandbox.ebury.io/cert_check", strings.NewReader(""))
if err != nil {
log.Fatal(err)
}
client := &http.Client{Transport: transport}
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
contents, err := ioutil.ReadAll(resp.Body)
log.Println(string(contents))
}
#!/usr/bin/php
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_SSLCERT, 'fullchain.pem');
curl_setopt($ch, CURLOPT_SSLKEY, 'privkey.pem');
curl_setopt($ch, CURLOPT_VERBOSE, true);
curl_setopt($ch, CURLOPT_URL,'https://trustedsandbox.ebury.io/cert_check');
$result=curl_exec($ch);
echo $result;
?>
import requests
response = requests.get('https://trustedsandbox.ebury.io/cert_check', cert=("fullchain.pem", "privkey.pem"))
print(response.text)
Response
CN=81be95eb.ngrok.io
If everything goes fine you will get a 200 response and the content of the response will be the subject DN of the certificate. You can now share the subject DN of the certificate with Ebury and the trusted connection with the regular endpoints will work without any further changes.
On the other hand, if there is a problem with the certificate or connection you might get one of these errors.
Status Code | Error |
---|---|
495 |
The certificate provided is invalid or the provided certificate's Subject DN does not matches the one for the client. |
496 |
There was not certificate provided. |
497 |
The connection was made using HTTP instead of HTTPS. |
You can check the next section in order to troubleshoot the issue.
Troubleshooting
In order to use this functionality the client you are connecting with must support the TLS 1.3 protocol, we don't support older versions of the protocol.
You need at least OpenSSL 1.1.1 in order to be able to use TLS 1.3, to check your openssl version you can use:
openssl version
Also, the connection must be done by using any of the following ciphers:
- TLS_AES_128_GCM_SHA256
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256
You can check the ciphers supported by doing:
openssl ciphers -v | grep TLSv1.3
If you can run any of these commands and get a successfull verification you are good to go
openssl s_client -tls1_3 -ciphersuites 'TLS_AES_128_GCM_SHA256' -connect tls13.cloudflare.com:443
openssl s_client -tls1_3 -ciphersuites 'TLS_AES_256_GCM_SHA384' -connect tls13.cloudflare.com:443
openssl s_client -tls1_3 -ciphersuites 'TLS_CHACHA20_POLY1305_SHA256' -connect tls13.cloudflare.com:443
Example Workflow
If you follow the Authentication guidelines you'll have implemented the means to access the API. The following sections describe how to secure a trade, add a beneficiary and make a payment. For more detail on each of these activities please see the relevant sections.
Get a Quote
curl -X POST \
"https://api.ebury.io/quotes?quote_type=quote&client_id=$client_id" \
-H "Authorization: Bearer $access_token" \
-H "Content-Type: application/json" \
-d '{
"trade_type": "spot",
"buy_currency": "EUR",
"amount": 1500.0,
"operation": "buy",
"sell_currency": "GBP",
"value_date": "2016-09-20"
}'
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"book_trade": "/trades?client_id=TAICLI00003"e_id=9ff9aee7a6d5f5e1b797165ffe580d74",
"buy_amount": 1500.0,
"buy_currency": "EUR",
"inverse_rate": 0.910995,
"inverse_rate_symbol": "GBPEUR",
"quote_id": "9ff9aee7a6d5f5e1b797165ffe580d74",
"quoted_rate": 1.097701,
"quoted_rate_symbol": "EURGBP",
"sell_amount": 1366.49,
"sell_currency": "GBP",
"value_date": "2016-10-27"
}
To execute a trade, you need to call the Quotes endpoint and get a quote. As already discussed in Getting Started to get a quote you need the following:
- The authentication flow completed with an access token to hand;
- The correct client identifier, retrieved from the ID token generated by the Token endpoint.
The response contains a quote_id
and a URL that you can use to book the trade. For more details on the Quotes API please refer to the Getting Quotes section.
Client Identifier
The client identifier is an entity Ebury uses to differentiate between different accounts in our data model. Majority of customers will only have one client identifier, but some may have multiple accounts and thus multiple identifiers.
Book a Trade
curl -X POST \
"https://api.ebury.io/trades?quote_id=$quote_id&client_id=$client_id" \
-H "Authorization: Bearer $access_token" \
-H "Content-Type: application/json" \
-d '{
"reason": "Travel costs",
"trade_type": "spot"
}'
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"bank_account": {
"account_number": "99999999",
"iban": "GB99TEST999999999999",
"swift_code": "TESTGB99",
"bank_identifier": "999999",
"bank_identifier_type": "GBP Sort Code",
"bank_name": "Name of the Bank",
"bank_address_line_1": "123 Sesame Street",
"bank_address_line_2": "Apartment 01-02",
"bank_city": "London",
"bank_post_code": "SW1W9QB"
},
"trade_id": "EBPOTR432737",
"maturiy_date": "2016-10-29T15:30:00.52Z"
}
With the quote identifier you can now book a trade to fund payment, calling the trades endpoint. Due to anti-money laundering a reason for making the trade needs to be specified; the API allows this to be a freeform value at the time of writing but future versions may introduce validation of the reason submitted.
The response contains a trade_id you can now book payments for known beneficiaries. For more details on the Trades API please refer to the Making Trades section.
Add a Beneficiary
curl -X POST \
"https://api.ebury.io/beneficiaries?client_id=$client_id" \
-H "Authorization: Bearer $access_token" \
-H "Content-Type: application/json" \
-d '{
"name": "John Doe",
"email_notification": true,
"address_line_1": "123 Sesame Street",
"post_code": "456",
"country_code": "GB",
"bank_country_code": "GB",
"bank_currency_code": "GBP",
"account_number": "99999998",
"swift_code": "TESTGBGB999",
"iban": "TESTGBGB9999999999",
}'
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"active": "True",
"address_line_1": null,
"aml_status": "Not Checked",
"bank_accounts": [
{
"account_id": 9999,
"account_number": "99999998",
"bank_address_line_1": null,
"bank_country_code": "GB",
"bank_currency_code": "GBP",
"bank_identifier": null,
"bank_name": null,
"correspondent_account": null,
"correspondent_swift_code": null,
"iban": "TESTGBGB9999999999",
"swift_code": "TESTGBGB999"
}
],
"beneficiary_id": "EBPBEN999999",
"country_code": "GB",
"created": "2016-10-25",
"email_addresses": [],
"email_notification": true,
"name": "John Doe",
"post_code": null
}
With the trade booked you can create a beneficiary who will be the recipient of part or all of the trade (of course you only need to create a beneficiary once, they are stored and can be reused later).
A beneficiary ID and account ID are returned that you can use to make a payment. For more details on the Beneficiaries API please refer to the Managing Beneficiaries section.
Make a Payment
curl -X POST \
"https://api.ebury.io/payments?client_id=$client_id" \
-H "Authorization: Bearer $access_token" \
-H "Content-Type: application/json" \
-d '{
"trade_id": "EBPOTR999999",
"async": false,
"payments":[
{
"beneficiary_id": "EBPBEN999999",
"account_id": "99999",
"amount": 10.50,
"payment_date": "2016-10-30",
"reference": "2016-10-29",
"email_beneficiary": true
}
]
}'
Response
HTTP/1.1 201 Created
Content-Type: application/json
[
{
"payment_id": "PI999999",
"payment_instruction": "/documents?type=pi&id=PI999999&client_id=TAICLI00003",
"payment_receipt": "Not available",
"status": "Validating beneficiary information"
}
]
Everything is now in place to book on or more payments, using the trade_id and beneficiary and account IDs returned from the create beneficiary step.
A payment_id will be returned together with links to download the payment instruction and receipt documents when available; if you are set-up to to pay immediately the payment will be made when:
- The beneficiary is validated;
- Funds are available;
- The payment date is reached.
If the payment requires authorisation an additional PATCH method will be required; refer to the notes in the Making Payments section for details.
Clients
Get Clients
Retrieve the list of clients which a contact can access, including their brands and status.
Request Headers
GET /clients HTTP/1.1
Authorization: string
Query Parameters
Name | Field Type | Location | Max Length | Accepted Values | Mandatory | Additional Info |
---|---|---|---|---|---|---|
page |
integer |
query |
>=1 |
N |
The desired page number for pagination. Default value is 1 |
|
page_size |
integer |
query |
>=1 |
N |
The number of items per page for pagination. Default value is 50 |
Response
[
{
"brand_name": "Ebury",
"client_id": "EBPCLI285330",
"client_name": "Ebury Partners UK",
"status": "Active"
},
{
"brand_name": "Ebury",
"client_id": "EBPCLI285313",
"client_name": "Ebury Partners ES",
"status": "Active"
},
{
"brand_name": "Ebury",
"client_id": "EBPCLI285314",
"client_name": "Ebury Partners BE",
"status": "Active"
}
]
A successful request will return a 200 OK response with a response body consisting of an array of objects with the following fields:
Name | Field Type | Location | Max Length | Additional Info |
---|---|---|---|---|
content-type |
application/json |
header |
||
x-total-count |
integer |
header |
Total number of entries returned. | |
content-length |
string |
header |
||
brand_name |
string |
body |
The brand of the client (e.g. Ebury). | |
client_id |
string |
body |
The client identificator (e.g. EBPCLIXXXX). | |
client_name |
string |
body |
The name of the client. | |
status |
string |
body |
It can be: “Active”, “Inactive”, “Closed” or “Blocked”. |
Getting Quotes
Get an estimate or firm quote:
- An estimate is as it's described: the current rates on offer within the Ebury platform with no firm quote;
- A firm quote returns a reference (a
quote_id
) that can be used to book a trade.
Get an estimate or firm quote
POST /quotes?client_id=$client_id"e_type=$quote_type HTTP/1.1
Authorization: string
Content-Type: application/json
{
"trade_type": "string",
"sell_currency": "string",
"buy_currency": "string",
"amount": "number",
"operation": "string",
"value_date": "string"
}
Obtain either an estimate or firm quote; estimates are for reference only, while a firm quote can be used to book a trade.
Request Headers
Header | Description |
---|---|
Content-Type Required |
application/json |
Query Parameters
Parameter | Description |
---|---|
quote_type Required |
The type of quote you are requesting. Acceptable values:
|
client_id Required |
The client identifier you are requesting this quote for |
Request Body
Field | Description |
---|---|
trade_type Required |
The type of trade you require a quote for. Acceptable values:
|
sell_currency Required |
Sell currency |
buy_currency Required |
Buy currency |
amount Required |
Amount in double format |
operation Required |
The operation you want to perform. Acceptable values:
|
value_date |
The date you want the quote. If the value date is not provided or is invalid then the quote will be returned for next available value date. |
Estimate Quote Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"estimated_rate": "number",
"estimated_rate_symbol": "string",
"inverse_rate": "number",
"inverse_rate_symbol": "string",
"fee_amount": "number",
"fee_currency": "string",
"value_date": "string",
"warning": "string"
}
Quote requests with a quote_type
of estimate
will return a 200 OK
response with the following response body.
Fields
Field | Description |
---|---|
estimated_rate Always |
The estimated rate |
estimated_rate_symbol Always |
The symbol of estimated rate |
inverse_rate Always |
Inverse rate |
inverse_rate_symbol Always |
The symbol of inverse rate |
fee_amount Always |
Fee amount |
fee_currency Always |
Fee currency |
value_date Always |
Date on which quote is requested |
warning |
A warning is only returned if the requested value date was not valid and the next available date has been returned. |
Firm Quote Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"quote_id": "string",
"sell_currency": "string",
"sell_amount": "number",
"buy_currency": "string",
"buy_amount": "number",
"quoted_rate": "number",
"quoted_rate_symbol": "string",
"inverse_rate": "number",
"inverse_rate_symbol": "string",
"value_date": "string",
"book_trade": "string",
"warning": "string"
}
Quote requests with a quote_type
of quote
will return a 201 Created
response with the following response body.
Fields
Field | Description |
---|---|
quote_id Always |
Quote identifier. Used to create book a trade at the Trades endpoint |
sell_currency Always |
Sell currency |
sell_amount Always |
Sell amount |
buy_currency Always |
Buy currency |
buy_amount Always |
Buy amount |
quoted_rate Always |
The rate quoted |
quoted_rate_symbol Always |
The symbol of rate quoted |
inverse_rate Always |
The inverse rate |
inverse_rate_symbol Always |
The symbol of inverse rate |
value_date Always |
Date on which trade active |
book_trade |
Call this endpoint to book the trade (refer to Trades documentation for required payload) |
warning |
A warning is only returned if the requested value date was not valid and the next available date has been returned. |
Get FX markets availability
curl --location --request GET '/quotes/fx-availability?client_id=XXXXXX' \
--header 'Authorization: $token' \
--header 'Content-Type: application/json'
import requests
import json
url = "/quotes/fx-availability?client_id=XXXXXX"
payload={}
headers = {
'Authorization': token,
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "/quotes/fx-availability?client_id=XXXXXX"
method := "GET"
client := &http.Client {
}
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Authorization", token)
req.Header.Add("Content-Type", "application/json")
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
<?php
#!/usr/bin/php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => '/quotes/fx-availability?client_id=XXXXXX',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Authorization: $token',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
The endpoint can be used to understand if foreign exchange can be initiated at that time or not. It is useful in instances which want to proactively manage whether or not to allow the user to attempt FX rather than throwing an error after the FX initiation request.
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Response
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"fx_available": "boolean",
}
A successful request will return a 200 OK response with the following response body.
Fields
Name | Description |
---|---|
fx_available ALWAYS |
True if the FX market is available for creating quote and trades. False if otherwise. |
Making Trades
Create a Trade
POST /trades?client_id=$client_id"e_id=$quote_id HTTP/1.1
Authorization: string
Content-Type: application/json
{
"reference": "string",
"reason": "string",
"external_reference_id": "string",
"convert": "boolean"
}
Initiate a new trade.
Request Headers
Header | Description |
---|---|
Content-Type Required |
application/json |
Query Parameters
Parameter | Description |
---|---|
quote_id Required |
The identifier of the quote, obtained from making a firm quote |
client_id Required |
The ID of the client |
Request Body
Fields
Name | Description |
---|---|
reason Required |
Reason for trade. See ReasonForTradeValues for acceptable values. |
reference |
Reference for the trade. |
external_reference_id |
API external reference id for the trade. |
convert |
Intention behind the trade. When set to true , trade will be executed and funds will be transferred between two Ebury wallets. When false , trade will be executed only when it is linked to at least one payment. By default, the field is set to false . |
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"trade_id": "string",
"bank_account": {
"account_number": "string",
"iban": "string",
"swift_code": "string",
"bank_identifier": "string",
"bank_identifier_type": "string",
"bank_name": "string",
"bank_address_line_1": "string",
"bank_address_line_2": "string",
"bank_city": "string",
"bank_post_code": "string"
},
"maturity_date": "string",
"initial_margin_amount": "number",
"initial_margin_due_date": "string"
}
A successfully created trade will return a 201 Created
response with the following response body.
Fields
Name | Description |
---|---|
trade_id Required |
Trade identifier |
bank_account Required |
An existing bank account |
maturity_date Required |
Limit date and time (UTC) in which funds must be received by Ebury |
initial_margin_amount |
Only for forwards. Trade's deposit amount |
initial_margin_due_date |
Only for forwards. Date on or before which deposit must be received by Ebury. Date and time are in UTC. |
Get all trades
GET /trades?client_id=$client_id HTTP/1.1
Authorization: string
Get all the trades for a given client ID.
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
trade_type |
Filter the response to include only trades with a matching type, which are specified by an array[string] Acceptable values:
|
parent_trade_id |
Parent identifier for drawdown trades |
page |
The desired page number for pagination. Default value is 1 . |
page_size |
The number of items per page for pagination. Default value is 50 . |
mass_payment_id |
Filter by related mass payment's uuid. |
mass_payment_external_reference_id |
Filter by related mass payment's external reference. |
buy_currency |
Filter by buy currency. |
status |
Filter trade by statuses. Separated by comma Acceptable values:
|
external_reference_id |
Filter by API external reference id. |
from_maturity_date |
Only return trades with trade maturity date on or after the from_maturity_date. YYYY-MM-DD format. |
to_maturity_date |
Only return trades with trade maturity date on or before the to_maturity_date. YYYY-MM-DD format. |
from_order_date |
Only return trades with trade order date on or after the from_order_date. YYYY-MM-DD format. |
to_order_date |
Only return trades with trade order date on or before the to_order_date. YYYY-MM-DD format. |
Response
HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1
[
{
"trade_id": "string",
"trade_type": "string",
"status": "string",
"buy_currency": "string",
"buy_amount": "number",
"sell_currency": "string",
"sell_amount": "number",
"rate": "number",
"rate_symbol": "string",
"order_date": "string",
"maturity_date": "string",
"fee_currency": "string",
"fee_amount": "number",
"synthetic": "boolean",
"trade_receipt": "string",
"reference": "string",
"parent_trade_id": "string"
}
]
A successful request will return a 200 OK
response with the response body containing a list of trade objects presented with the BookedTrade model. In addition the total number of entries is available in the header field x-total-count
.
Get a trade
GET /trades/$trade_id?client_id=$client_id HTTP/1.1
Authorization: string
Get a trade with a specific trade_id.
Path Parameters
Parameter | Description |
---|---|
trade_id Required |
Trade identifier |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"trade_id": "string",
"trade_type": "string",
"status": "string",
"buy_currency": "string",
"buy_amount": "number",
"sell_currency": "string",
"sell_amount": "number",
"rate": "number",
"rate_symbol": "string",
"order_date": "string",
"maturity_date": "string",
"fee_currency": "string",
"fee_amount": "number",
"synthetic": "boolean",
"parent_trade_id": "string",
"trade_receipt": "string",
"reference": "string"
}
A successful request will return a 200 OK
response with the requested trade object in response body presented with the BookedTrade model.
Trade Models
These models are returned by the get all trades and get a trade endpoints.
BookedTrade
{
"trade_id": "string",
"trade_type": "string",
"status": "string",
"buy_currency": "string",
"buy_amount": "number",
"sell_currency": "string",
"sell_amount": "number",
"rate": "number",
"rate_symbol": "string",
"order_date": "string",
"maturity_date": "string",
"fee_currency": "string",
"fee_amount": "number",
"synthetic": "boolean",
"parent_trade_id": "string",
"trade_receipt": "string",
"reference": "string",
"convert": "boolean"
}
This model is a representation of a booked trade.
Fields
Name | Description |
---|---|
trade_id Always |
Trade identifier |
trade_type Always |
Trade type |
status Always |
Status of the trade |
buy_currency Always |
Buy currency code |
buy_amount Always |
Buy amount |
sell_currency Always |
Sell currency code |
sell_amount Always |
Sell amount |
rate Always |
Booked rate |
rate_symbol Always |
The symbol of booked rate |
order_date Always |
Order date |
maturity_date Always |
Limit date and time (UTC) in which funds must be received by Ebury |
fee_currency Always |
Fee currency |
fee_amount Always |
Fee amount |
parent_trade_id Always |
Parent trade ID (not null for drawdown trades) |
synthetic Always |
Identifies as a synthetic future contracts |
trade_receipt |
The URL to get the trade receipt |
reference |
Additional trade reference e.g., invoice number |
convert |
Intention behind the trade (either to move funds internally between Ebury wallets or to link payments to trades) |
TradeStatus
This is an enumeration of the status of a trade, and can be found in the BookedTrade model.
Values
Value | Description |
---|---|
Created |
Trade has been created |
Funds In Partially |
The trade has been partially funded |
Funds in Full |
The trade has been fully funded |
Funds Out Partially Allocated |
The proceeds of the trade have been only partially allocated to payments out |
Funds Out Full Allocated |
The proceeds of the trade have been fully allocated to payments out |
Closed |
The proceeds of the trade have been fully paid out and the trade is closed |
Cancelled |
The trade has been cancelled |
ReasonForTradeValues
This is list of acceptable values for the reason
field when creating a trade.
Values
Value | Description |
---|---|
charitable_aid |
Charitable Aid |
payment_for_goods |
Payment for identifiable goods |
capital_investment |
Direct capital investment in an enterprise |
payment_for_services |
Payment for identifiable services |
repatriation_of_goods |
Repatriation of sale of identifiable goods |
repatriation_of_services |
Repatriation of sale of identifiable services |
property_purchase |
Property purchase |
mortage_repayment |
Mortage repayment |
property_rental_or_maintenance |
Property rental/maintenance |
salary_payroll |
Salary/Payroll |
travel_costs |
Travel costs |
living_costs |
Living costs |
repayment_of_loan |
Repayment of a loan |
balance_hedging |
Balance sheet hedging |
repatriation_from_investment |
Repatriation of revenues from investments |
portfolio_netting |
Portfolio netting |
not_related_to_goods_or_services |
Other not related to identifiable goods or services (only Spot type) |
other |
Other |
Getting Metadata
The Metadata endpoints provide the following information:
- A full list of supported currencies;
- A digest of the requirements for provisioning beneficiaries
Get beneficiary metadata
GET /metadata/beneficiary HTTP/1.1
Authorization: string
Describes the fields required to provision a valid beneficiary for a given country/currency combination:
- All supported countries are described by this API;
- For each supported country, any currency that has specific requirements is defined in the currencies list. If there are no specific requirements the value
default
should be used. - The response of this endpoint is in line with the SWIFT ISO20022 standards. Please note, the mandatory fields and business rules around beneficiary address defined via this endpoint, does not apply to Ebury Mass Payments customers. Should you have any doubts, please reach out to us.
Response
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"country": "string",
"currencies": [
{
"currency": "string",
"mandatory": [
[
"string"
]
],
"optional_data": [
"string"
]
}
],
"reason_required": "boolean"
}
]
A successful request will return a 200 OK
response with a response body consisting of a list of the following objects.
Fields
Name | Description |
---|---|
country |
Two-letter country identifier |
currencies |
List of currency objects; will contain at least one default object |
currencies.currency |
Currency symbol |
currencies.mandatory |
List of mandatory field combinations; combinations are presented as lists |
currencies.optional |
List of optional fields |
reason_required |
boolean flag |
Get currency metadata
GET /metadata/currency HTTP/1.1
Authorization: string
Describe a currency
Query Parameters
Parameter | Description |
---|---|
data_only |
Exclude reason_required flag from response; Defaults to false |
Response
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"currency": "string",
"buy": {
"cutoff_days": "integer",
"cutoff_time": "string"
},
"reason_required": "boolean",
"sell": {
"cutoff_days": "integer",
"cutoff_time": "string"
},
"invalid_value_dates": {
"YYYY-MM-DD": "string"
}
}
]
A successful request will return a 200 OK
response with a response body consisting of a list of the following objects.
Fields
Name | Description |
---|---|
buy |
Information of this currency if it is used as "buy" currency |
buy.cutoff_days |
Cutoff days of the currency |
buy.cutoff_time |
Cutoff time for the currency in GMT/UTC |
currency |
Currency symbol |
invalid_value_dates |
Invalid trading dates and their reasons |
invalid_value_dates.YYYY-MM-DD |
Invalid trading date; the value of this key is the reason the date is invalid |
reason_required |
Show if reason required for this currency is mandatory |
sell |
Information of this currency if it is used as "sell" currency |
sell.cutoff_days |
Cutoff days of the currency |
sell.cutoff_time |
Cutoff time for the currency in GMT/UTC |
Managing Beneficiaries
Create a new beneficiary
POST /beneficiaries?client_id=$client_id HTTP/1.1
Authorization: string
Content-Type: application/json
{
"name": "string",
"email_addresses": [
"string"
],
"email_notification": "boolean",
"address_line_1": "string",
"street_name": "string",
"building_number": "string",
"floor": "string",
"apartment_office_number": "string",
"city": "string",
"state_region": "string",
"post_code": "string",
"country_code": "string",
"account_number": "string",
"bank_address_line_1": "string",
"bank_country_code": "string",
"bank_currency_code": "string",
"bank_identifier": "string",
"bank_name": "string",
"correspondent_account": "string",
"correspondent_swift_code": "string",
"iban": "string",
"inn": "string",
"kbk": "string",
"kio": "string",
"kpp": "string",
"purpose_of_payment": "string",
"reason_for_trade": "string",
"reference_information": "string",
"beneficiary_reference": "string",
"russian_central_bank_account": "string",
"swift_code": "string",
"vo": "string"
}
Create a new client beneficiary. Beneficiary will require verification before payments can be made
Request Headers
Header | Description |
---|---|
Content-Type Required |
application/json |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Request Body
Fields
Name | Description |
---|---|
name Required |
The name of the beneficiary |
email_addresses |
List of email addresses |
email_notification Required |
Whether the beneficiary should receive email notification of payments |
address_line_1 * |
The first address line of the beneficiary (deprecated)* |
street_name * |
The street name of the beneficiary |
building_number * |
The building number of the beneficiary |
floor * |
The floor of the beneficiary |
apartment_office_number * |
The apartment/office number of the beneficiary |
city *Required |
The city of the beneficiary |
state_region * |
The state/region of the beneficiary |
post_code |
The postcode of the beneficiary |
country_code Required |
The ISO 3166-1 alpha-2 code of the beneficiary's country |
account_number |
The account number of the bank account |
bank_address_line_1 |
The first address line of the bank |
bank_country_code Required |
The ISO 3166-1 alpha-2 code of the bank's country |
bank_currency_code Required |
The ISO 4217 code of the bank account's currency |
bank_identifier |
The identifier of the bank |
bank_name |
Name of the bank account holder |
correspondent_account |
The account for the correspondent account of the bank |
correspondent_swift_code |
The SWIFT code for the correspondent account of the bank |
iban |
The IBAN of the bank account |
inn |
Unique Taxpayer Personal Identification Number for legal entities registered in Russia. |
kbk |
The KBK of the bank account |
kio |
Tax ID for foreign legal entities in Russia. |
kpp |
The KPP of the bank account |
purpose_of_payment |
The purpose of payment is mandatory when the beneficiary account has specific currency types. See the section PurposeOfPayment for the currencies and their acceptable values. |
reason_for_trade |
The reason for trade of the bank account |
reference_information |
The reference information which will be used as the default payment reference during payment initiation. |
beneficiary_reference |
Unique external reference ID submitted by the client for the beneficiary. |
russian_central_bank_account |
20-digit code for Russian banks. |
swift_code |
The SWIFT code of the bank account |
vo |
Code of currency transaction established by the Central Bank of Russia to describe the purpose of the payment. |
* This field and the related rule becomes operational from October 2024. Further communication will follow over emails. Please note, it does not apply to Ebury Mass Payments customers in Production.
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"name": "string",
"email_addresses": [
"string"
],
"email_notification": "boolean",
"address_line_1": "string",
"street_name": "string",
"building_number": "string",
"floor": "string",
"apartment_office_number": "string",
"city": "string",
"state_region": "string",
"post_code": "string",
"country_code": "string",
"bank_accounts": [
{
"account_number": "string",
"bank_address_line_1": "string",
"bank_country_code": "string",
"bank_currency_code": "string",
"bank_identifier": "string",
"bank_identifier_type": "string",
"bank_name": "string",
"correspondent_account": "string",
"correspondent_swift_code": "string",
"iban": "string",
"inn": "string",
"kbk": "string",
"kio": "string",
"kpp": "string",
"reason_for_trade": "string",
"reference_information": "string",
"russian_central_bank_account": "string",
"swift_code": "string",
"vo": "string",
"account_id": "integer"
}
],
"beneficiary_id": "string",
"created": "string",
"aml_status": "string",
"active": "string",
"beneficiary_reference": "string",
}
A successful request will return a 201 Created
response with the response body containing a Beneficiary object.
Get beneficiaries
GET /beneficiaries?client_id=$client_id HTTP/1.1
Authorization: string
Get all beneficiaries for a given client
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
page |
The desired page number for pagination. Default value is 1 . |
page_size |
The number of items per page for pagination. Default value is 50 . |
iban |
The IBAN of the beneficiary. |
account_number |
The account number of the beneficiary. |
bank_currency_code |
The currency of the beneficiary's account. |
bank_identifier |
The bank identifier of the beneficiary's account. |
beneficiary_reference |
Unique external reference ID submitted by the client for the beneficiary. |
Response
HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1
[
{
"name": "string",
"email_addresses": [
"string"
],
"email_notification": "boolean",
"address_line_1": "string",
"street_name": "string",
"building_number": "string",
"floor": "string",
"apartment_office_number": "string",
"city": "string",
"state_region": "string",
"post_code": "string",
"country_code": "string",
"bank_accounts": [
{
"account_number": "string",
"bank_address_line_1": "string",
"bank_country_code": "string",
"bank_currency_code": "string",
"bank_identifier": "string",
"bank_identifier_type": "string",
"bank_name": "string",
"correspondent_account": "string",
"correspondent_swift_code": "string",
"iban": "string",
"inn": "string",
"kbk": "string",
"kio": "string",
"kpp": "string",
"purpose_of_payment": "string",
"reason_for_trade": "string",
"reference_information": "string",
"russian_central_bank_account": "string",
"swift_code": "string",
"vo": "string",
"account_id": "integer"
}
],
"beneficiary_id": "string",
"created": "string",
"aml_status": "string",
"active": "string",
"beneficiary_reference": "string",
}
]
A successful request will return a 200 OK
response with the response body containing a list of Beneficiary objects. In addition the total number of entries is available in the header field x-total-count
.
Get a single beneficiary
GET /beneficiaries/$beneficiary_id?client_id=$client_id HTTP/1.1
Authorization: string
Get a single beneficiary by beneficiary ID
Path Parameters
Parameter | Description |
---|---|
beneficiary_id Required |
The ID of the beneficiary |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "string",
"email_addresses": [
"string"
],
"email_notification": "boolean",
"address_line_1": "string",
"street_name": "string",
"building_number": "string",
"floor": "string",
"apartment_office_number": "string",
"city": "string",
"state_region": "string",
"post_code": "string",
"country_code": "string",
"bank_accounts": [
{
"account_number": "string",
"bank_address_line_1": "string",
"bank_country_code": "string",
"bank_currency_code": "string",
"bank_identifier": "string",
"bank_identifier_type": "string",
"bank_name": "string",
"correspondent_account": "string",
"correspondent_swift_code": "string",
"iban": "string",
"inn": "string",
"kbk": "string",
"kio": "string",
"kpp": "string",
"purpose_of_payment": "string",
"reason_for_trade": "string",
"reference_information": "string",
"russian_central_bank_account": "string",
"swift_code": "string",
"vo": "string",
"account_id": "integer"
}
],
"beneficiary_id": "string",
"created": "string",
"aml_status": "string",
"active": "string"
"beneficiary_reference": "string",
}
A successful request will return a 200 OK
response with the response body containing a Beneficiary object.
Update a beneficiary
PATCH /beneficiaries/$beneficiary_id?client_id=$client_id HTTP/1.1
Authorization: string
Content-Type: application/json
{
"name": "string",
"email_addresses": [
"string"
],
"email_notification": "boolean",
"address_line_1": "string",
"street_name": "string",
"building_number": "string",
"floor": "string",
"apartment_office_number": "string",
"city": "string",
"state_region": "string",
"post_code": "string",
"country_code": "string",
"bank_accounts": [
{
"account_number": "string",
"bank_address_line_1": "string",
"bank_country_code": "string",
"bank_currency_code": "string",
"bank_identifier": "string",
"bank_identifier_type": "string",
"bank_name": "string",
"correspondent_account": "string",
"correspondent_swift_code": "string",
"iban": "string",
"inn": "string",
"kbk": "string",
"kio": "string",
"kpp": "string",
"purpose_of_payment": "string",
"reason_for_trade": "string",
"reference_information": "string",
"russian_central_bank_account": "string",
"swift_code": "string",
"vo": "string",
"account_id": "integer"
}
],
"beneficiary_id": "string",
"created": "string",
"aml_status": "string",
"active": "string",
"beneficiary_reference": "string",
}
Update a single beneficiary by beneficiary ID, using a list of names and values.
Request Headers
Header | Description |
---|---|
Content-Type Required |
application/json |
Path Parameters
Parameter | Description |
---|---|
beneficiary_id Required |
The ID of the beneficiary you want to update |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Request Body
After a beneficiary has received a payment, the only fields available for modification are:
email_addresses
email_notification
beneficiary_reference
Fields
Name | Description |
---|---|
name |
The name of the beneficiary |
email_addresses |
List of email addresses |
email_notification |
Whether the beneficiary should receive email notification of payments |
address_line_1 * |
The first address line of the beneficiary (deprecated)* |
street_name * |
The street name of the beneficiary |
building_number * |
The building number of the beneficiary |
floor * |
The floor of the beneficiary |
apartment_office_number * |
The apartment/office number of the beneficiary |
city * |
The city of the beneficiary |
state_region * |
The state/region of the beneficiary |
post_code |
The postcode of the beneficiary |
country_code |
The ISO 3166-1 alpha-2 code of the beneficiary's country |
account_number |
The account number of the bank account |
bank_address_line_1 |
The first address line of the bank |
bank_country_code Required |
The ISO 3166-1 alpha-2 code of the bank's country |
bank_currency_code Required |
The ISO 4217 code of the bank account's currency |
bank_identifier |
The identifier of the bank |
bank_name |
Name of the bank account holder |
correspondent_account |
The account for the correspondent account of the bank |
correspondent_swift_code |
The SWIFT code for the correspondent account of the bank |
iban |
The IBAN of the bank account |
inn |
Unique Taxpayer Personal Identification Number for legal entities registered in Russia. |
kbk |
The KBK of the bank account |
kio |
Tax ID for foreign legal entities in Russia. |
kpp |
The KPP of the bank account |
purpose_of_payment |
The purpose of payment is mandatory when the beneficiary account has specific currency types. See the section PurposeOfPayment for the currencies and their acceptable values. |
reason_for_trade |
The reason for trade of the bank account |
reference_information |
The reference information which will be used as the default payment reference during payment initiation. |
beneficiary_reference |
Unique external reference ID submitted by the client for the beneficiary. |
russian_central_bank_account |
20-digit code for Russian banks. |
swift_code |
The SWIFT code of the bank account |
vo |
Code of currency transaction established by the Central Bank of Russia to describe the purpose of the payment. |
* This field and the related rule becomes operational from October 2024. Further communication will follow over emails. Please note, it does not apply to Ebury Mass Payments customers in Production.
Response
HTTP/1.1 204 No Content
A successful request will return a 204 No Content
response with an empty response body.
Delete a beneficiary
DELETE /beneficiaries/$beneficiary_id?client_id=$client_id HTTP/1.1
Authorization: string
Delete a single beneficiary by beneficiary ID
Path Parameters
Parameter | Description |
---|---|
beneficiary_id Required |
The ID of the beneficiary you want to delete |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Response
HTTP/1.1 204 No Content
A successful request will return a 204 No Content
response with an empty response body.
Beneficiary Models
BankAccount
{
"account_number": "string",
"bank_address_line_1": "string",
"bank_country_code": "string",
"bank_currency_code": "string",
"bank_identifier": "string",
"bank_identifier_type": "string",
"bank_name": "string",
"correspondent_account": "string",
"correspondent_swift_code": "string",
"iban": "string",
"inn": "string",
"kbk": "string",
"kio": "string",
"kpp": "string",
"purpose_of_payment": "string",
"reason_for_trade": "string",
"reference_information": "string",
"russian_central_bank_account": "string",
"swift_code": "string",
"vo": "string",
"account_id": "string"
}
Bank account data. Refer to the Metadata API for valid field combinations.
Fields
Name | Description |
---|---|
account_number |
The account number of the bank account |
bank_address_line_1 |
The first address line of the bank |
bank_country_code Required |
The ISO 3166-1 alpha-2 code of the bank's country |
bank_currency_code Required |
The ISO 4217 code of the bank account's currency |
bank_identifier |
The identifier of the bank |
bank_identifier_type |
The identifier type of the bank |
bank_name |
Name of the bank account holder |
correspondent_account |
The account for the correspondent account of the bank |
correspondent_swift_code |
The SWIFT code for the correspondent account of the bank |
iban |
The IBAN of the bank account |
inn |
The INN of the bank account |
kbk |
The KBK of the bank account |
kio |
The KIO of the bank account |
kpp |
The KPP of the bank account |
purpose_of_payment |
The purpose of payment is mandatory when the beneficiary account has specific currency types. See the section PurposeOfPayment for the currencies and their acceptable values. |
reason_for_trade |
The reason for trade of the bank account |
reference_information |
The reference information which will be used as the default payment reference during payment initiation. |
russian_central_bank_account |
The Russian central account number of the bank account |
swift_code |
The SWIFT code of the bank account |
vo |
The VO of the bank account |
account_id Required |
The identifier of the bank account |
BeneficiaryCoreData
{
"name": "string",
"email_addresses": [
"string"
],
"email_notification": "boolean",
"address_line_1": "string",
"street_name": "string",
"building_number": "string",
"floor": "string",
"apartment_office_number": "string",
"city": "string",
"state_region": "string",
"post_code": "string",
"country_code": "string"
}
This model is a representation of a beneficiary's core data.
Fields
Name | Description |
---|---|
name Required |
The name of the beneficiary |
email_addresses |
The list of beneficiary's email addresses |
email_notification Required |
Whether the beneficiary should receive email notification of payments |
address_line_1 |
The first address line of the beneficiary |
street_name * |
The street name of the beneficiary |
building_number * |
The building number of the beneficiary |
floor * |
The floor of the beneficiary |
apartment_office_number * |
The apartment/office number of the beneficiary |
city *Required |
The city of the beneficiary |
state_region * |
The state/region of the beneficiary |
post_code |
The postcode of the beneficiary |
country_code Required |
The ISO 3166-1 alpha-2 code of the beneficiary's country |
* This field and the related rule becomes operational from October 2024. Further communication will follow over emails. Please note, it does not apply to Ebury Mass Payments customers in Production.
Beneficiary
{
"name": "string",
"email_addresses": [
"string"
],
"email_notification": "boolean",
"address_line_1": "string",
"street_name": "string",
"building_number": "string",
"floor": "string",
"apartment_office_number": "string",
"city": "string",
"state_region": "string",
"post_code": "string",
"country_code": "string",
"bank_accounts": [
{
"account_number": "string",
"bank_address_line_1": "string",
"bank_country_code": "string",
"bank_currency_code": "string",
"bank_identifier": "string",
"bank_identifier_type": "string",
"bank_name": "string",
"correspondent_account": "string",
"correspondent_swift_code": "string",
"iban": "string",
"inn": "string",
"kbk": "string",
"kio": "string",
"kpp": "string",
"purpose_of_payment": "string",
"reason_for_trade": "string",
"reference_information": "string",
"russian_central_bank_account": "string",
"swift_code": "string",
"vo": "string",
"account_id": "integer"
}
],
"beneficiary_id": "string",
"created": "string",
"aml_status": "string",
"active": "string",
"beneficiary_reference": "string",
}
This model is a representation of a beneficiary.
Fields
Name | Description |
---|---|
name Always |
The name of the beneficiary |
email_addresses |
The list of beneficiary's email addresses |
email_notification Always |
Whether the beneficiary should receive email notification of payments |
address_line_1 |
The first address line of the beneficiary |
street_name * |
The street name of the beneficiary |
building_number * |
The building number of the beneficiary |
floor * |
The floor of the beneficiary |
apartment_office_number * |
The apartment/office number of the beneficiary |
city *Always |
The city of the beneficiary |
state_region * |
The state/region of the beneficiary |
post_code |
The postcode of the beneficiary |
country_code Always |
The ISO 3166-1 alpha-2 code of the beneficiary's country |
bank_accounts Always |
The list of beneficiary's bank accounts |
beneficiary_id Always |
The beneficiary ID |
created Always |
Creation date of the beneficiary |
aml_status Always |
AML status of the beneficiary |
active Always |
True if beneficiary is active, False otherwise |
beneficiary_reference |
Unique external reference ID submitted by the client for the beneficiary. |
* This field and the related rule becomes operational from October 2024. Further communication will follow over emails. Please note, it does not apply to Ebury Mass Payments customers in Production.
AMLStatus
AML status of the Beneficiary
Values
Value | Description |
---|---|
OK |
Beneficiary checks completed, ready to be paid |
Pending Review |
Reviewing beneficiary information |
Pending information |
Awaiting beneficiary information |
Blocked |
Client account blocked |
PurposeOfPayment
Valid purpose of payment values.
When country is China, the following purpose of payment values are mandatory only for CNY currency
When country is United Arab Emirates, the following purpose of payment values are mandatory for all currencies
Getting Accounts
The Accounts API allows you to retrieve information for your accounts.
Retrieve a list of accounts
GET /accounts?client_id=$client_id HTTP/1.1
Authorization: string
Get all accounts for a given client.
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
currencies |
A comma-separated list of currency codes compliant to ISO 4217 |
Response
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"account_id": "uuid",
"account_subtype": "account_subtype",
"account_type": "account_type",
"account_details": [
{
"account_address": "account_address",
"account_name": "account_name",
"account_number": "account_number",
"account_number_type": "account_number_type",
"bank_identifier": "bank_identifier",
"bank_identifier_type": "bank_identifier_type"
},
{
"account_address": "account_address",
"account_name": "account_name",
"account_number": "account_number",
"account_number_type": "account_number_type",
"bank_identifier": "bank_identifier",
"bank_identifier_type": "bank_identifier_type"
}
],
"currency": "currency",
"status": "account_status"
},
{
"account_id": "uuid",
"account_subtype": "account_subtype",
"account_type": "account_type",
"account_details": [
{
"account_address": "account_address",
"account_name": "account_name",
"account_number": "account_number",
"account_number_type": "account_number_type",
"bank_identifier": "bank_identifier",
"bank_identifier_type": "bank_identifier_type"
},
{
"account_address": "account_address",
"account_name": "account_name",
"account_number": "account_number",
"account_number_type": "account_number_type",
"bank_identifier": "bank_identifier",
"bank_identifier_type": "bank_identifier_type"
}
],
"currency": "currency",
"status": "account_status"
}
]
A successful request will return a 200 OK
response with the response body containing a list of AccountDetails
objects.
Retrieve an account
GET /accounts/$account_id?client_id=$client_id HTTP/1.1
Authorization: string
Retrieve a single account by account ID.
Path Parameters
Parameter | Description |
---|---|
account_id Required |
The UUID of the account |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"account_id": "uuid",
"account_subtype": "account_subtype",
"account_type": "account_type",
"account_details": [
{
"account_address": "account_address",
"account_name": "account_name",
"account_number": "account_number",
"account_number_type": "account_number_type",
"bank_identifier": "bank_identifier",
"bank_identifier_type": "bank_identifier_type"
},
{
"account_address": "account_address",
"account_name": "account_name",
"account_number": "account_number",
"account_number_type": "account_number_type",
"bank_identifier": "bank_identifier",
"bank_identifier_type": "bank_identifier_type"
}
],
"currency": "currency",
"status": "account_status"
}
A successful request will return a 200 OK
response with the response body containing an AccountData
object.
Account Models
These models are returned by the get all accounts and get an account endpoints.
AccountData
[
{
"account_id": "uuid",
"account_subtype": "account_subtype",
"account_type": "account_type",
"account_details": [
{
"account_address": "account_address",
"account_name": "account_name",
"account_number": "account_number",
"account_number_type": "account_number_type",
"bank_identifier": "bank_identifier",
"bank_identifier_type": "bank_identifier_type"
},
{
"account_address": "account_address",
"account_name": "account_name",
"account_number": "account_number",
"account_number_type": "account_number_type",
"bank_identifier": "bank_identifier",
"bank_identifier_type": "bank_identifier_type"
}
],
"currency": "currency",
"status": "account_status"
},
{
"account_id": "uuid",
"account_subtype": "account_subtype",
"account_type": "account_type",
"account_details": [
{
"account_address": "account_address",
"account_name": "account_name",
"account_number": "account_number",
"account_number_type": "account_number_type",
"bank_identifier": "bank_identifier",
"bank_identifier_type": "bank_identifier_type"
},
{
"account_address": "account_address",
"account_name": "account_name",
"account_number": "account_number",
"account_number_type": "account_number_type",
"bank_identifier": "bank_identifier",
"bank_identifier_type": "bank_identifier_type"
}
],
"currency": "currency",
"status": "account_status"
}
]
This model is a representation of an account within Ebury.
Fields
Name | Description |
---|---|
currency Always |
Identification of the currency in which the account is held |
account_details Always |
The list of AccountDetail s for this currency |
status Always |
The AccountStatus of the account |
account_id Always |
The UUID of the account |
account_type Always |
The AccountType of the account |
account_subtype Always |
The AccountSubType of the account |
AccountDetails
{
"account_id": "uuid",
"account_subtype": "account_subtype",
"account_type": "account_type",
"account_details": [
{
"account_address": "account_address",
"account_name": "account_name",
"account_number": "account_number",
"account_number_type": "account_number_type",
"bank_identifier": "bank_identifier",
"bank_identifier_type": "bank_identifier_type"
},
{
"account_address": "account_address",
"account_name": "account_name",
"account_number": "account_number",
"account_number_type": "account_number_type",
"bank_identifier": "bank_identifier",
"bank_identifier_type": "bank_identifier_type"
}
],
"currency": "currency",
"status": "account_status"
}
This model is a representation of account data associated with an Account.
Fields
Name | Description |
---|---|
account_address Always |
The address of the account |
account_name Always |
The name or names of the account owner(s) represented at an account level |
account_number Always |
The number of the account |
account_number_type Always |
The AccountNumberType of the account number |
bank_identifier Always |
The identifier of the bank |
bank_identifier_type Always |
The BankIdentifierType of the bank identifier |
AccountStatus
This is an enumeration of the statuses of an account.
Values
Value | Description |
---|---|
Enabled |
Account is enabled. |
Disabled |
Account is disabled. |
AccountType
This is an enumeration of the types of an account.
Values
Value | Description |
---|---|
Personal |
Individual account. |
Business |
Corporate account. |
AccountSubType
This is an enumeration of sub types of an account (product family group).
Values
Value | Description |
---|---|
EMoney |
AccountNumberType
This is an enumeration of number types of an account.
Values
Value | Description |
---|---|
IBAN |
|
BBAN |
BankIdentifierType
This is an enumeration of bank identifier types, to comply with ISO20022 code
s related to Clearing System Identification, with the addition of SWBIC
for swift international payments.
Values
Value | Description |
---|---|
SWBIC |
Used for swift international payments. |
other | Please refer to ExternalClearingSystemIdentification1Code inside Clearing System Identification of ISO20022. |
Getting Account Details
Generate New Collection Account (Coming soon)
API clients will be able to call the POST Account details endpoint to request a new client named collection account from Ebury using the API.
POST /account-details?client_id=$client_id HTTP/1.1
Authorization: string
{
“alias”: “string”,
"country": "string",
"currency": “string”
}
Request Headers
Query Parameters
Name | Field Type | Location | Max Length | Mandatory | Additional Info |
---|---|---|---|---|---|
client_id |
string |
query |
32 |
Y |
The client identifier you are requesting this account for. |
Request Body
Name | Field Type | Location | Max Length | Mandatory | Additional Info |
---|---|---|---|---|---|
alias |
string |
body |
50 |
N |
User-friendly alias for the account. Only present (and mandatory) for dedicated accounts. |
country |
string |
body |
2 |
Y |
ISO 3166-1 Alpha-2 code. |
currency |
string |
body |
3 |
Y |
ISO 4217 Alpha-3 code. |
Response
A successful request will return a 200 OK
response with the response body containing a list of AccountDetails
objects. In addition, the total number of entries retrieved is available in header field x-total-count
.
Getting Account Details Metadata
Retrieve the list of currencies and countries where a customer can open a virtual account. Bear in mind that not all accounts can be opened automatically from the API, in certain cases, it is required to contact the Ebury relationship manager.
Request Headers
GET /account-details/metadata?client_id=$client_id HTTP/1.1
Authorization: string
[
{
“auto_create”: “boolean”,
"country": "string",
"currency": “string”
},
]
Query Parameters
Name | Field Type | Location | Max Length | Accepted Values | Mandatory | Additional Info |
---|---|---|---|---|---|---|
client_id |
string |
query |
32 |
Y |
||
country |
string |
query |
2 |
Regex: [A-Z]{2} |
N |
ISO 3166-1 Alpha-2 code. |
currency |
string |
query |
3 |
Regex: [A-Z]{3} |
N |
ISO 4217 Alpha-3 code. |
page |
integer |
query |
>=1 |
N |
||
page_size |
integer |
query |
>=1 |
N |
Response
[
{
"auto_create": false,
"country": "BE",
"currency": "GBP"
},
{
"auto_create": false,
"country": "GB",
"currency": "EUR"
},
{
"auto_create": false,
"country": "GB",
"currency": "GBP"
},
{
"auto_create": false,
"country": "GB",
"currency": "USD"
},
{
"auto_create": false,
"country": "NL",
"currency": "AED"
}
]
A successful request will return a 200 OK response with a response body consisting of an array of objects with the following fields:
Name | Field Type | Location | Max Length | Additional Info |
---|---|---|---|---|
content-type |
application/json |
header |
||
x-total-count |
integer |
header |
Total number of entries returned. | |
auto-create |
boolean |
body |
If this is set to “false”, it means that the client is not able to automatically create an account in that currency and country. | |
country |
string |
body |
2 |
An ISO 3166-1 Alpha-2 code will be returned. |
currency |
string |
body |
3 |
An ISO 4217 Alpha-3 code will be returned. |
Mark an account as primary
Mark the account as primary (default) for its holder and currency. Only dedicated accounts can be set as primary, trying this operation for a pooled account will return an error.
Request Headers
POST /account-details/$account_details_id/make-default?client_id=$client_id HTTP/1.1
Authorization: string
Query Parameters
Name | Field Type | Location | Max Length | Accepted Values | Mandatory | Additional Info |
---|---|---|---|---|---|---|
client_id |
string |
query |
32 |
Y |
ID of the client that owns the account details | |
account_details_id |
string |
path |
36 |
uuid |
Y |
Unique ID of the account |
Response
A successful request will return a 204 No Content response.
Retrieve Account Details
Retrieve the account details for a given client, possibly filtered by some criteria.
Request Headers
GET /account-details?client_id=$client_id HTTP/1.1
Authorization: string
Query Parameters
Name | Field Type | Location | Max Length | Accepted Values | Mandatory | Additional Info |
---|---|---|---|---|---|---|
client_id |
string |
query |
32 |
Y |
ID of the client that owns the account details | |
account_details_type |
string |
query |
-dedicated -pooled |
N |
Filter by account details type | |
account_id |
string |
query |
36 |
uuid |
N |
Filter by the unique ID of the account |
country |
string |
query |
2 |
Regex: [A-Z]{2} |
N |
Filter by the country of the account (ISO Code 2) |
currency |
string |
query |
3 |
Regex: [A-Z]{3} |
N |
Filter by the currency of the account (ISO Code 3) |
alias |
string |
query |
50 |
N |
Filter by the user-friendly alias of the account. Only dedicated accounts can be filtered by alias. | |
page |
integer |
query |
>=1 |
N |
Default value is 1. | |
page_size |
integer |
query |
>=1 |
N |
Default value is 50. |
Response
A successful request will return a 200 OK
response with the response body containing a list of AccountDetails
objects. In addition, the total number of entries retrieved is available in header field x-total-count
.
Update Account Details
Update or change the alias for a given account for a given client. Only dedicated accounts can be patched, trying to patch a pooled account will return an error.
Request Headers
PATCH /account-details/$account_details_id?client_id=$client_id HTTP/1.1
Authorization: string
Content-Type: application/json
{
"alias": "NL EUR Account"
}
Query Parameters
Name | Field Type | Location | Max Length | Accepted Values | Mandatory | Additional Info |
---|---|---|---|---|---|---|
client_id |
string |
query |
32 |
Y |
ID of the client that owns the account details | |
account_details_id |
string |
path |
36 |
uuid |
Y |
Unique ID of the account |
Request Body
Name | Field Type | Location | Max Length | Mandatory |
---|---|---|---|---|
alias |
string |
body |
50 |
Y |
Response
A successful request will return a 200 OK
response with the response body containing a list of AccountDetails
objects. In addition, the total number of entries retrieved is available in header field x-total-count
.
Account Details Model
These models are returned by Retrieving Account Details, Generate New Collection Account and Update Account Details endpoints.
AccountDetails Data
[
{
"account_details_id": "42101706-b568-410f-88f5-43f39869304f",
"account_details_type": "dedicated",
"account_holder_address": "",
"account_holder_name": "Implementation Account",
"account_id": "5b40a865-72ed-5159-96ba-8d4389d0051e",
"alias": "NL EUR Account",
"country": "NL",
"created": "2020-12-10 13:01:13.857898",
"currency": "EUR",
"domestic": null,
"financial_institution_address": "Claude Debussylaan 26\n1028 MD, Amsterdam",
"financial_institution_name": "EBURY PARTNERS NETHERLANDS",
"international": {
"account_number": "NL55RABO3717231707",
"account_number_type": "IBAN",
"bank_identifier": "EBURNL21",
"bank_identifier_type": "SWBIC"
},
"modified": "2020-12-10 13:31:46.929423",
"primary": true,
"status": "confirmed"
},
{
"account_details_id": "c5733e6d-9de8-46ce-e731-07d6fa4093b6",
"account_details_type": "pooled",
"account_holder_address": "100 Victoria Street London SW1E 5JL",
"account_holder_name": "Ebury Partners UK Limited",
"account_id": null,
"country": "GB",
"currency": "NZD",
"domestic": {
"account_number": "4006003",
"account_number_type": "BBAN",
"bank_identifier": "312840",
"bank_identifier_type": "NZNCC"
},
"financial_institution_address": "Citibank Centre 23 Customs Street East\n1140\nAUCKLAND",
"financial_institution_name": "Citibank NA New Zealand Branch",
"international": {
"account_number": "4006003",
"account_number_type": "BBAN",
"bank_identifier": "CITINZ2X",
"bank_identifier_type": "SWBIC"
},
"status": "confirmed"
}
]
This model is a representation of account details within Ebury.
Fields
Name | Description |
---|---|
account_id Always |
The UUID of the account. |
account_details_id Always |
(uuid) Unique ID of the account details |
account_details_type Always |
The AccountDetailsType |
alias |
User-friendly alias for the account. Only available (and mandatory) on dedicated accounts |
account_holder_address Always |
The address of the account holder |
account_holder_name Always |
The name of the account holder |
country Always |
The country of the account-details. An ISO 3166-1 Alpha-2 code will be returned |
currency Always |
Identification of the currency in which the account is held. An ISO 3166-1 Alpha-2 code will be returned |
domestic |
Domestic information of the account. It can be null. See the list of Domestic AccountDetails |
international |
International information of the account. It can be null. See the list of International AccountDetails |
financial_institution_name |
The name of the FI |
financial_institution_address |
The address of the FI |
modified |
In YYYY-MM-DD hh:mm:ss.SSS format. Datetime of last modification (for dedicated accounts only) |
primary |
If "true" the account is marked as default (for dedicated accounts only) |
status Always |
The AccountDetailsStatus |
AccountDetails Type
This is an enumeration of account-details types.
VALUES
Value | Description |
---|---|
Dedicated |
The account is dedicated |
Pooled |
The account is pooled |
Domestic AccountDetails
This model is a representation of domestic account-details associated with an Account.
FIELDS
Name | Description |
---|---|
domestic.account_number |
The number of the account |
domestic.account_number_type |
Account Number Type |
domestic.bank_identifier |
The identifier of the bank. |
domestic.bank_identifier_type |
Bank Identifier Type |
International AccountDetails
This model is a representation of international account-details associated with an Account.
FIELDS
Name | Description |
---|---|
international.account_number |
The number of the account |
international.account_number_type |
Account Number Type |
international.bank_identifier |
The identifier of the bank. |
international.bank_identifier_type |
Bank Identifier Type |
AccountDetailsStatus
This is an enumeration of the statuses of an account.
VALUES
Value | Description |
---|---|
Pending |
The account is pending to be created |
Confirmed |
The account creation is created |
Failed |
The account creation has failed |
Getting Balances
The Balances API allows you to retrieve the balances for your accounts.
Get balances for all accounts
GET /balances?client_id=$client_id HTTP/1.1
Authorization: string
Get all balances for all accounts for a given client.
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
currencies |
A comma-separated list of currency codes compliant to ISO 4217 |
balance_types |
A list of available balance types. One of BalanceTypes . Default is InterimAvailable . |
Response
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"account_id": "5358dae1-269e-c21e-952b-b8b8d597dcce",
"amount": {
"amount": "0.0000",
"currency": "USD"
},
"credit_debit_indicator": "Credit",
"datetime": "2019-10-24T22:37:22.547",
"type": "InterimAvailable"
},
{
"account_id": "c18a42df-6652-d462-351b-0485a6d6bc16",
"amount": {
"amount": "50112.8500",
"currency": "EUR"
},
"credit_debit_indicator": "Credit",
"datetime": "2019-10-24T22:37:22.547",
"type": "InterimAvailable"
}
]
A successful request will return a 200 OK
response with the response body containing a list of BalanceData
objects.
Get balances for a single account
GET /accounts/$account_id/balances?client_id=$client_id HTTP/1.1
Authorization: string
Retrieve all balances for a single account by account ID.
Path Parameters
Parameter | Description |
---|---|
account_id |
The UUID of the account |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
balance_types |
A list of available balance types. One of BalanceTypes . Default is InterimAvailable . |
Response
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"account_id": "5358dae1-269e-c21e-952b-b8b8d597dcce",
"amount": {
"amount": "150.0000",
"currency": "USD"
},
"credit_debit_indicator": "Credit",
"datetime": "2019-10-24T22:37:22.547",
"type": "InterimAvailable"
}
]
A successful request will return a 200 OK
response with the response body containing a list of BalanceData
objects.
Balance Models
These models are returned by the get all balances and get an account balances endpoints.
BalanceData
{
"account_id": "5358dae1-269e-c21e-952b-b8b8d597dcce",
"amount": {
"amount": "150.0000",
"currency": "USD"
},
"credit_debit_indicator": "Credit",
"datetime": "2019-10-24T22:37:22.547",
"type": "InterimAvailable"
}
This model is a representation of a single balance for an account within Ebury.
Fields
Name | Description |
---|---|
account_id Always |
The UUID of the account |
amount Always |
Object of Amount |
credit_debit_indicator Always |
One of CreditDebitIndicator |
datetime Always |
Date and time |
type Always |
Type of the balance. One of BalanceType |
Amount
{
"amount": "150.0000",
"currency": "USD"
}
This model is a representation of a balance/transaction amount.
Fields
Name | Description |
---|---|
amount Always |
The balance/transaction amount |
currency Always |
The ISO 4217 code of the balance currency |
BalanceType
This is an enumeration of the balance types of an account.
Values
Value | Description |
---|---|
InterimAvailable |
Available balance calculated in the course of the account servicer's business day. |
RequiredFunds |
Funds required on account taking in mind future payments, trades and fees. |
CreditDebitIndicator
Whether the balance/transaction amount is credit or debit
Values
Value | Description |
---|---|
Debit |
The amount is debit |
Credit |
The amount is credit |
Getting Currencies
The Currencies API allows you to retrieve the information about currencies of the client.
Get currencies
GET /currencies?client_id=$client_id HTTP/1.1
Authorization: string
Get all currencies for a given client.
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
trade_type |
Type of trade. One of TradeTypes . Default value is spot . |
currency |
A comma-separated list of currency codes compliant to ISO 4217 |
Response
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"currency": "USD",
"available_for_trading": true,
"credit_limit": "-901220.0000",
"default": false,
"holidays": [
"2017-06-08T00:00:00+05"
],
"currency_limit": "734408.5000",
"decimals": 2,
"cutoff": {
"days": 0,
"time": "23:00:00+00"
},
"buy_allowed": true,
"sell_allowed": true
},
{
"currency": "GBP",
"available_for_trading": true,
"credit_limit": "3998760.0000",
"default": true,
"holidays": [
"2017-06-09T00:00:00+05",
"2017-06-08T00:00:00+05"
],
"currency_limit": "500000.0000",
"decimals": 2,
"cutoff": {
"days": 0,
"time": "23:00:00+00"
},
"buy_allowed": true,
"sell_allowed": true
}
]
A successful request will return a 200 OK
response with the response body containing a list of CurrencyInfo objects.
Currency Models
TradeType
This is an enumeration of the balance types of an account.
Values
Value | Description |
---|---|
spot |
Spot trade |
forward |
Forward trade |
CurrencyInfo
{
"currency": "USD",
"available_for_trading": true,
"credit_limit": "-901220.0000",
"default": false,
"holidays": [
"2017-06-08T00:00:00+05"
],
"currency_limit": "734408.5000",
"decimals": 2,
"cutoff": {
"days": 0,
"time": "23:00:00+00"
},
"buy_allowed": true,
"sell_allowed": true
}
This model is a representation of a single currency of an Ebury client.
Fields
Name | Description |
---|---|
currency Always |
Currency symbol |
available_for_trading Always |
Is this currency available to trade |
credit_limit Always |
Limit of the credit |
default Always |
Is this default currency of the client |
holidays Always |
List of holidays in a format ISO-8601 |
currency_limit Always |
Limit of the currency |
decimals Always |
Decimal settings of the client for the currency |
cutoff Always |
Object of Cutoff |
buy_allowed Always |
Is client allowed to buy this currency |
sell_allowed Always |
Is client allowed to sell this currency |
Cutoff
{
"days": 0,
"time": "23:00:00+00"
}
This model is a representation of a cutoff for a currency.
Fields
Name | Description |
---|---|
days Always |
Cutoff days for the currency |
time Always |
Cutoff time for the currency. Includes TZ data in ISO format |
Getting Transactions
The Transactions API allows you to retrieve the transactions for your accounts.
Get transactions for all accounts
GET /transactions?client_id=$client_id HTTP/1.1
Authorization: string
Get all transactions for all accounts for a given client.
Transactions can be filtered by value date and time. If no value date and time filter is set, it will return the latest 50 transactions.
Retrieving transactions with value date and time before June 1st, 2019 is not supported yet.
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
credit_debit_indicator |
Only return transactions specified by this parameter. Accepted values are 'credit' and 'debit'. |
currencies |
A comma-separated list of currency codes compliant to ISO 4217 |
from_value_datetime |
Only return transactions with value date and time after this UTC date and time. YYYY-MM-DDThh:mm format |
to_value_datetime |
Only return transactions with value date and time before this UTC date and time. YYYY-MM-DDThh:mm format |
page |
The desired page number for pagination. Default value is 1 . |
page_size |
The number of items per page for pagination. Default value is 50 . |
transaction_type |
Only return transactions of the specified TransactionType . |
Response
HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1
[
{
"account_id": "c18a42df-6652-d462-351b-0485a6d6bc16",
"additional_transaction_information": "EURGBP 0.876804 - other",
"amount": {
"amount": "100.00",
"currency": "EUR"
},
"balance": {
"amount": {
"amount": "50212.85",
"currency": "EUR"
},
"credit_debit_indicator": "Credit",
"type": "InterimAvailable"
},
"booking_datetime": "2019-11-11T20:37:30.598",
"client_id": "EBPCLI285330",
"credit_debit_indicator": "Credit",
"creditor_account": {
"account_name": "EBURY OFFICE ACC CHF",
"account_number": "",
"bank_identifier": "",
"bank_identifier_code": "",
"iban": "GB78BARC12345678901234",
"swift": ""
},
"creditor_name": "Jorge Chapa",
"debtor_account": {
"account_name": "Cool Account",
"account_number": "1234567890",
"bank_identifier": "123456",
"bank_identifier_code": "",
"iban": "",
"swift": "RACZHUH1123"
},
"debtor_name": "Jorge Corp",
"status": "Booked",
"transaction_id": "3ae5b450-1e1a-b116-1fde-3cb4f0353e16",
"transaction_information": "Bought EUR EBPOTR002772",
"transaction_reference": "EBPOTR002772",
"transaction_type": "credit",
"value_datetime": "2019-11-11T20:37:30.598"
}
]
A successful request will return a 200 OK
response with the response body containing a list of TransactionData
objects.
In addition the total number of entries retrieved is available in header field x-total-count
.
Get transactions for a single account
GET /accounts/$account_id/transactions?client_id=$client_id HTTP/1.1
Authorization: string
Retrieve all transactions for a single account by account ID.
Transactions can be filtered by value date and time. If no value date and time filter is set, it will return the latest 50 transactions.
Retrieving transaction booked before June 1st, 2019 is not supported yet.
Path Parameters
Parameter | Description |
---|---|
account_id Required |
The UUID of the account |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
credit_debit_indicator |
Only return transactions specified by this parameter. Accepted values are 'credit' and 'debit'. |
from_value_datetime |
Only return transactions with value date and time after this UTC date and time. YYYY-MM-DDThh:mm format |
to_value_datetime |
Only return transactions with value date and time before this UTC date and time. YYYY-MM-DDThh:mm format |
page |
The desired page number for pagination. Default value is 1 . |
page_size |
The number of items per page for pagination. Default value is 50 . |
transaction_type |
Only return transactions of the specified TransactionType . |
Response
HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1
[
{
"account_id": "c18a42df-6652-d462-351b-0485a6d6bc16",
"additional_transaction_information": "EURGBP 0.876804 - other",
"amount": {
"amount": "100.00",
"currency": "EUR"
},
"balance": {
"amount": {
"amount": "50212.85",
"currency": "EUR"
},
"credit_debit_indicator": "Credit",
"type": "InterimAvailable"
},
"booking_datetime": "2019-11-11T20:37:30.598",
"client_id": "EBPCLI285330",
"credit_debit_indicator": "Credit",
"creditor_account": {
"account_name": "EBURY OFFICE ACC CHF",
"account_number": "",
"bank_identifier": "",
"bank_identifier_code": "",
"iban": "GB78BARC12345678901234",
"swift": ""
},
"creditor_name": "Jorge Chapa",
"debtor_account": {
"account_name": "Cool Account",
"account_number": "1234567890",
"bank_identifier": "123456",
"bank_identifier_code": "",
"iban": "",
"swift": "RACZHUH1123"
},
"debtor_name": "Jorge Corp",
"status": "Booked",
"transaction_id": "3ae5b450-1e1a-b116-1fde-3cb4f0353e16",
"transaction_information": "Bought EUR EBPOTR002772",
"transaction_reference": "EBPOTR002772",
"transaction_type": "credit",
"value_datetime": "2019-11-11T20:37:30.598"
}
]
A successful request will return a 200 OK
response with the response body containing a list of TransactionData
objects.
In addition the total number of entries retrieved is available in header field x-total-count
.
Get a single transaction
GET /accounts/$account_id/transactions/$transaction_id?client_id=$client_id HTTP/1.1
Authorization: string
X-Contact-ID: string
Retrieve a single transaction for an account by account ID and transaction ID.
Path Parameters
Parameter | Description |
---|---|
account_id Required |
The UUID of the account |
transaction_id Required |
The UUID of the transaction |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"account_id": "c18a42df-6652-d462-351b-0485a6d6bc16",
"additional_transaction_information": "EURGBP 0.876804 - other",
"amount": {
"amount": "100.00",
"currency": "EUR"
},
"balance": {
"amount": {
"amount": "50212.85",
"currency": "EUR"
},
"credit_debit_indicator": "Credit",
"type": "InterimAvailable"
},
"booking_datetime": "2019-11-11T20:37:30.598",
"client_id": "EBPCLI285330",
"credit_debit_indicator": "Credit",
"creditor_account": {
"account_name": "EBURY OFFICE ACC CHF",
"account_number": "",
"bank_identifier": "",
"bank_identifier_code": "",
"iban": "GB78BARC12345678901234",
"swift": ""
},
"creditor_name": "Jorge Chapa",
"debtor_account": {
"account_name": "Cool Account",
"account_number": "1234567890",
"bank_identifier": "123456",
"bank_identifier_code": "",
"iban": "",
"swift": "RACZHUH1123"
},
"debtor_name": "Jorge Corp",
"status": "Booked",
"transaction_id": "3ae5b450-1e1a-b116-1fde-3cb4f0353e16",
"transaction_information": "Bought EUR EBPOTR002772",
"transaction_reference": "EBPOTR002772",
"transaction_type": "credit",
"value_datetime": "2019-11-11T20:37:30.598"
}
A successful request will return a 200 OK
response with the response body containing a TransactionData
object.
Transaction Models
These models are returned by the get all transactions and get an account transactions endpoints.
TransactionData
{
"account_id": "c18a42df-6652-d462-351b-0485a6d6bc16",
"additional_transaction_information": "EURGBP 0.876804 - other",
"amount": {
"amount": "100.00",
"currency": "EUR"
},
"balance": {
"amount": {
"amount": "50212.85",
"currency": "EUR"
},
"credit_debit_indicator": "Credit",
"type": "InterimAvailable",
},
"booking_datetime": "2019-11-11T20:37:30.598",
"client_id": "EBPCLI285330",
"credit_debit_indicator": "Credit",
"creditor_account": {
"account_name": "EBURY OFFICE ACC CHF",
"account_number": "",
"bank_identifier": "",
"bank_identifier_code": "",
"iban": "GB78BARC12345678901234",
"swift": ""
},
"creditor_name": "Jorge Chapa",
"debtor_account": {
"account_name": "Cool Account",
"account_number": "1234567890",
"bank_identifier": "123456",
"bank_identifier_code": "",
"iban": "",
"swift": "RACZHUH1123"
},
"debtor_name": "Jorge Corp",
"status": "Booked",
"transaction_id": "3ae5b450-1e1a-b116-1fde-3cb4f0353e16",
"transaction_information": "Bought EUR EBPOTR002772",
"transaction_reference": "EBPOTR002772",
"transaction_type": "credit",
"value_datetime": "2019-11-11T20:37:30.598"
}
This model is a representation of a single transaction for an account within Ebury.
Fields
Name | Description |
---|---|
account_id Always |
The UUID of the account |
additional_transaction_information Always |
Additional information for the transaction |
amount Always |
The Amount of the transaction |
balance Always |
The Balance of the transaction |
booking_datetime Always |
Date and time (UTC) when the transaction was booked |
client_id Always |
Identifier of the client |
credit_debit_indicator Always |
One of CreditDebitIndicator |
creditor_account Always |
The Bank Account information of the creditor |
creditor_name Always |
Name of the creditor |
debtor_account Always |
The Bank Account information of the debtor |
debtor_name Always |
Name of the debtor |
status Always |
One of TransactionStatus |
transaction_id Always |
The UUID of the transaction |
transaction_information Always |
Basic information for the transaction |
transaction_reference Always |
Reference for the transaction |
transaction_type Always |
The TransactionType of the transaction |
value_datetime Always |
Value date and time (UTC) of the transaction |
TransactionBalance
{
"amount": {
"amount": "50212.85",
"currency": "EUR"
},
"credit_debit_indicator": "Credit",
"type": "InterimAvailable"
}
This model is a representation of the balance of the account (rounded to the currency decimal places) when the transaction happens.
Fields
Name | Description |
---|---|
amount Always |
The Amount of the transaction |
credit_debit_indicator Always |
One of CreditDebitIndicator |
type Always |
Type of the balance. One of BalanceType |
TransactionStatus
This is an enumeration of the transaction status types
Values
Value | Description |
---|---|
Booked |
Booked |
TransactionType
This is an enumeration of the transaction types
Values
Value | Description |
---|---|
credit |
Record of any activity that generates a positive(credit) transaction on the account. |
debit |
Record of any activity that generates a negative(debit) transaction on the account (debit from the customer account). |
incoming |
Record of the incoming funds from an external source (credit into customer account from third parties, other clients, client’s own accounts at other banks etc.,). incoming as a type exclusively covers a subset of transactions which are originally of the type credit. |
margin |
Record of the deposits, refunds related to forward trades. |
payment_returned |
Record created when funds can’t be credited to the beneficiary and the counterparty returned the funds to the customer. |
CreditorDebtorAccount
{
"account_name": "Cool Account",
"account_number": "1234567890",
"bank_identifier": "123456",
"bank_identifier_code": "",
"iban": "",
"swift": "RACZHUH1123"
}
This model is a representation of the bank account information for the creditor/debtor of a transaction
Fields
Name | Description |
---|---|
account_name Always |
The name of the account's owner |
account_number Always |
Account number |
bank_identifier Always |
Account bank identifier |
bank_identifier_code Always |
Account bank identifier code (UK sort code, US ABA/FedWire, etc.) |
iban Always |
Account IBAN |
swift Always |
Account SWIFT code |
Getting Statements
The Statements API allows you to create and retrieve the statement for an account in pdf, csv or mt940 formats.
Create statement for an account
POST /accounts/$account_id/statements/file?client_id=$client_id HTTP/1.1
Authorization: string
Content-Type: application/json
{
"from_value_datetime": "2019-12-01T00:00:00",
"to_value_datetime": "2019-12-01T23:59:59"
}
Generate a statement asynchronously in PDF
, CSV
or MT940
format for a given account.
It is not possible to generate statements for periods longer than 31 days.
In order to retrieve the generated statement go to Retrieve a statement for an account
Path Parameters
Parameter | Description |
---|---|
account_id Required |
The UUID of the account |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
format |
The File Format in which the statement will be generated. Default value is pdf . |
Request Body
Fields
Name | Description |
---|---|
from_value_datetime Required |
Only return transactions after this value date (included). It is not possible to generate statements for periods longer than 31 days. It used to take into account the time, but it does not any longer: it defaults to the start of the date. YYYY-MM-DDThh:mm format |
to_value_datetime |
Only return transactions before this value date (included). It is not possible to generate statements for periods longer than 31 days. It used to take into account the time, but it does not any longer: it defaults to the end of the date. YYYY-MM-DDThh:mm format. Only required for CSV and MT940 formats. For PDF format defaults to the current date and time |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"url": "/accounts/f51303e6-a591-6331-7a63-0a39794c712a/statements/c01d8acb-ec28-7a94-169f-fff7bf092fab/file"
}
A successful request will return a 202 ACCEPTED
response with the response body containing a StatementFileData
object.
StatementFileData
{
"url": "/accounts/f51303e6-a591-6331-7a63-0a39794c712a/statements/c01d8acb-ec28-7a94-169f-fff7bf092fab/file"
}
This model containts the url that is needed in order to retrieve the statement once its processing has finished.
Fields
Name | Description |
---|---|
url Always |
The url needed to retrieve the statement. It contains two UUID values, the first one (from the left) is the account id and the second one is the statement id. |
Retrieve a statement for an account
GET /accounts/$account_id/statements/$statement_id/file?client_id=$client_id HTTP/1.1
Authorization: string
Get a previously generated statement.
For MT940
statements, the result will be a zip file with one MT940
file for each day in the given period.
If there are no transactions for a given day, an MT940
will be generated anyway for that day with the account information.
All the date and time values for the CSV
and PDF
statements will be localized in the client's contact time zone.
Path Parameters
Parameter | Description |
---|---|
account_id |
The UUID of the account |
statement_id |
The UUID of the statement |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Response
HTTP/1.1 202 OK
Content-Type: application/json
{
"status": "Pending"
}
A successful request will return either a 200 OK
with the statement file as an attachment if the statement processing has finished or a 202 ACCEPTED
and contain a StatementFileStatus
object with the status of the statement if it is not ready yet.
Statements Models
These models are used by the create and get statements endpoints.
StatementSupportedTypes
This is an enumeration of the supported formats for a statement
Values
Value | Description |
---|---|
pdf |
Generate a single statement in pdf format. |
csv |
Generate a single statement in csv format. |
mt940 |
Generate multiple statements, one for each day in the period, in mt940 format. The result will be a zip file with all the mt940 statements. |
StatementFileStatus
{
"status": "Pending"
}
This model is a representation of the current status of statement.
Fields
Name | Description |
---|---|
status Always |
The StatementStatus for the statement. |
StatementStatus
This is an enumeration of possible status in which a statement can be.
Values
Value | Description |
---|---|
Pending |
The statement has not been processed yet. |
Failed |
The statement processing failed. |
Making Payments
The Payments API allows you make payments to a known beneficiary with or without a trade associated with it.
In general, you can make payments in one of the two ways:
- Pay immediately: When a payment instruction is sent the payment will be made immediately if the beneficiary has been validated and funds are available, or as soon as validation and funding has been completed. With this set-up only the GET and POST HTTP methods are available. Should you need to stop or return a payment manual intervention will be required by the Operations team;
- Pay when authorised: Once a payment instruction has been sent an additional authorisation step is required to execute the payment: This step can either approve or reject the payment. With this set-up the PATCH and DELETE HTTP methods are available, to approve and reject the payment respectively. Note that if authorisation is required you require at least two contacts registered on your Ebury account as authorisation cannot be completed by one contact.
The choice of immediate payment or when authorised needs to be made when your Ebury account is created; you should consider carefully which set-up best fits your needs.
Create one or more new payments
POST /payments?client_id=$client_id HTTP/1.1
Authorization: string
Content-Type: application/json
{
"trade_id": "string",
"async": "boolean",
"purpose_of_payment": "string",
"payments": [
{
"beneficiary_id": "string",
"account_id": "string",
"amount": "number",
"email_beneficiary": "boolean",
"payment_date": "string",
"reference": "string"
}
]
}
Create one or more payments with a beneficiary_id
(mandatory only for trade-based payment and not needed for independent payments), account_id
and with or without an existing trade_id
. Payment processing can be made asynchronous by setting the async
flag in the request body. Please note, payments can be submitted without a trade_id
and they are referred to as independent payments. For these payments, there won’t be any currency conversion as the payment will be funded from the corresponding account’s balance. Therefore, these payments are not preceded by a conversion (quote and trade).
Request Headers
Header | Description |
---|---|
Content-Type Required |
application/json |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
include_errors Optional |
Can be set to true, if the API response should include further details on why the payments failed, if any. Defaults to false. |
Request Body
Fields
Name | Description |
---|---|
trade_id Optional |
Unique identifier of the trade the payment will be allocated to. When trade_id is not provided, the initiation is considered as an independent payment. It does not require FX before the payment |
async |
boolean flag to create the payment(s) asynchronously; defaults to false |
purpose_of_payment Optional |
A purpose of payment. Relevant (and optional) only for independent payments. The acceptable values are Reason for trade |
payments |
A list of payments to create |
payments.beneficiary_id Required |
The ID of the beneficiary |
payments.account_id Required |
The ID of the beneficiary's bank account |
payments.amount Required |
The payment amount |
payments.payment_date Required |
The date on which payment is required |
payments.reference Required |
Payment reference |
payments.email_beneficiary |
Whether the beneficiary should receive and email on payment |
Response
The response to a successful request will vary depending on the value of the async
value of the request.
HTTP/1.1 204 No Content
If async
is set to true
, a 204 No Content
response will be returned, as the request is being processed asynchronously.
HTTP/1.1 201 Created
Content-Type: application/json
[
{
"payment_id": "string",
"fee_amount": "number",
"fee_currency": "string",
"payment_instruction": "string",
"payment_receipt": "string",
"status": "string",
"reference": "string",
"warning": "string"
}
]
If async
is set to false
, a 201 Created
response will be returned with the with the following response body.
Fields
Name | Description |
---|---|
payment_id |
The payment identifier |
fee_amount |
Fee amount |
fee_currency |
Fee currency |
payment_instruction |
URI to download payment instruction |
payment_receipt |
URI to download payment receipt |
status |
The current status of the payment |
reference |
The payment reference |
warning |
A warning is returned only if the requested payment_date for an independent payment was not valid and the next available date has been returned |
Search or retrieve payments
GET /payments?client_id=$client_id HTTP/1.1
Authorization: string
Search or retrieve all payments for a given client ID
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
page |
The desired page number for pagination. Default value is 1 . |
page_size |
The number of items per page for pagination. Default value is 50 . |
reference |
Filter payments by reference. |
trade_id |
Filter payments by trade_id. |
external_reference_id |
Filter by payment’s external_reference_id. At the moment, it is possible only for payments initiated via the mass payments service. |
mass_payment_id |
Filter by related mass payment's uuid. |
mass_payment_external_reference_id |
Filter by related mass payment's external reference. |
multipayment_id |
Filter by related multipayment_id. Provide only the numerals of the multipayment_id. |
payment_currency |
Filter by payment currency |
from_payment_date |
Only return payments with payment date on or after this from_payment_date. YYYY-MM-DD format. |
to_payment_date |
Only return payments with payment date on or before this to_payment_date. YYYY-MM-DD format. |
from_created_date |
Only return payments with created date on or after this from_created_date. YYYY-MM-DD format. |
to_created_date |
Only return payments with created date on or before this to_created_date. YYYY-MM-DD format. |
pending_only |
If true , only return payments which are not yet executed (not in status Payment complete OR Payment rejected OR Payment cancelled ). Default value is false . |
include_all |
If true , return all payments regardless of the payment statuses. Default value is false . |
Response
HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1
[
{
"payment_id": "string",
"contact_id": "string",
"trade_id": "string",
"account_number": "string",
"amount": "number",
"bank_identifier": "string",
"beneficiary_name": "string",
"created_date": "string",
"external_reference_id": "string",
"fee_amount": "number",
"fee_currency": "string",
"iban": "string",
"payment_currency": "string",
"payment_date": "string",
"payment_instruction": "string",
"payment_receipt": "string",
"status": "string",
"swift_code": "string",
"authorised_by": "string",
"authorised_date": "string",
"rejected_by": "string",
"rejected_date": "string",
"cancelled_by": "string",
"cancelled_date": "string",
"authorisation_workflow": "string",
"invoice_required": "boolean",
"reference": "string"
}
]
A successful request will return a 200 OK
response with the response body containing list of Payment objects. In addition the total number of entries is available in the header field x-total-count
.
Retrieve a payment
GET /payments/$payment_id?client_id=$client_id HTTP/1.1
Authorization: string
Retrieve a payment with a given payment ID
Path Parameters
Parameter | Description |
---|---|
payment_id Required |
Unique idenifier for payment |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment_id": "string",
"contact_id": "string",
"trade_id": "string",
"account_number": "string",
"amount": "number",
"bank_identifier": "string",
"beneficiary_name": "string",
"created_date": "string",
"external_reference_id": "string",
"fee_amount": "number",
"fee_currency": "string",
"iban": "string",
"payment_currency": "string",
"payment_date": "string",
"payment_instruction": "string",
"payment_receipt": "string",
"status": "string",
"swift_code": "string",
"authorised_by": "string",
"authorised_date": "string",
"rejected_by": "string",
"rejected_date": "string",
"cancelled_by": "string",
"cancelled_date": "string",
"authorisation_workflow": "string",
"invoice_required": "boolean",
"reference": "string"
}
A successful request will return a 200 OK
response with the response body containing a Payment object.
Authorise or reject a payment
PATCH /payments/$payment_id?client_id=$client_id&action=$action HTTP/1.1
Authorization: string
HTTP/1.1 204 No Content
Authorise or reject a payment with a given payment ID (the requirement to authorise or reject payments depends on your account configuration)
Path Parameters
Parameter | Description |
---|---|
payment_id Required |
Unique idenifier for payment |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
action Required |
The action to take (authorise or reject ) |
Response
HTTP/1.1 204 No Content
A successful request will return a 204 No Content
response with an empty response body.
Delete a payment
DELETE /payments/$payment_id?client_id=$client_id HTTP/1.1
Authorization: string
Delete a payment with a given payment ID
Path Parameters
Parameter | Description |
---|---|
payment_id Required |
Unique idenifier for payment |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Response
HTTP/1.1 204 No Content
A successful request will return a 204 No Content
response with an empty response body.
Get the estimate fee of payments
GET /payments/fees_estimate?client_id=$client_id&payment_amount=$payment_amount&payment_currency=$payment_currency HTTP/1.1
Authorization: string
Retrieve the potential payment fee for sending a payment.
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
payment_amount Required |
The amount of the payment |
payment_currency Required |
The currency of the payment |
payment_country |
The destination country of the payment |
payment_intra_Ebury |
boolean flag to filter by Ebury intra payments or not |
Response
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"fee_amount": "number",
"fee_currency": "string",
"payment_currency": "string",
"payment_country": "string",
"payment_amount": "number",
"payment_instruction": "string",
"payment_is_intra": "boolean"
}
]
A successful request will return a 200 OK
response with the response body containing a list of Payment Fee objects.
Get the accurate fee of payments
GET /payments/fees?client_id=$client_id&payment_amount=$payment_amount&beneficiary_id=$beneficiary_id HTTP/1.1
Authorization: string
Retrieve the accurate payment fee for sending a payment to a particular beneficiary
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
payment_amount Required |
The amount of the payment |
beneficiary_id Required |
The beneficiary_id to whom payment needs to be made |
Response
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"beneficiary_id": "string",
"fee_amount": "number",
"fee_currency": "string",
"payment_amount": "number",
"payment_currency": "string",
"payment_country": "string",
"payment_is_intra": "boolean"
}
]
A successful request will return a 200 OK
response with the response body containing a list of Payment Fee objects.
Payment Models
Payment
{
"payment_id": "string",
"contact_id": "string",
"trade_id": "string",
"account_number": "string",
"amount": "number",
"bank_identifier": "string",
"beneficiary_name": "string",
"created_date": "string",
"external_reference_id": "string",
"fee_amount": "number",
"fee_currency": "string",
"iban": "string",
"payment_currency": "string",
"payment_date": "string",
"payment_instruction": "string",
"payment_receipt": "string",
"status": "string",
"swift_code": "string",
"authorised_by": "string",
"authorised_date": "string",
"rejected_by": "string",
"rejected_date": "string",
"cancelled_by": "string",
"cancelled_date": "string",
"authorisation_workflow": "string",
"invoice_required": "boolean",
"reference": "string"
}
This model is a representation of a payment.
Fields
Name | Description |
---|---|
payment_id Always |
Unique identifier for the payment |
contact_id Always |
Unique identifier of the contact who booked the payment |
trade_id Always |
Unique identifier of the trade the payment is allocated to |
multipayment_id |
Unique identifier for the multi payment |
mass_payment_id |
Unique identifier for the mass payment |
account_number |
Account number of the beneficiary |
amount |
Payment amount |
bank_identifier |
The identifier of the beneficiary's bank |
beneficiary_name |
Name of the beneficiary |
created_date |
Payment instruction created date |
external_reference_id |
Unique reference submitted by the client to identify the payment |
fee_amount |
Fee amount |
fee_currency |
Fee currency |
iban |
The IBAN of the beneficiary's bank account |
payment_currency |
Currency the payment was made in |
payment_date |
Target payment date |
payment_instruction |
URI to download payment instruction |
payment_receipt |
URI to download payment receipt |
status |
The current status of the payment |
swift_code |
The SWIFT code of the beneficiary's bank account |
authorised_by |
The user who authorised the payment |
authorised_date |
The date when payment was authorised |
rejected_by |
The user who rejected the payment |
rejected_date |
The date when payment was rejected |
cancelled_by |
The user who cancelled the payment |
cancelled_date |
The date when payment was cancelled |
authorisation_workflow |
The authorisation workflow of the payment Acceptable values:
|
invoice_required |
Whether or not the payment requires an invoice |
reference |
The payment reference |
Status
Status of the payments
Values
Value | Description |
---|---|
Need more beneficiary information |
Beneficiary information is not complete, more details are required. |
Validating beneficiary information |
Beneficiary information is complete, but not validated yet. |
Waiting for payment date |
Payment is ready to be executed, waiting for payment execution date. |
Payment complete |
Payment has been executed. |
Executing Payment |
Payment is in the process of being executed. |
Payment pending of authorization |
Payment has been verified but not authorised. |
Payment rejected |
Payment has been rejected. |
Payment cancelled |
Payment has been cancelled. |
Payment Fee
{
"fee_amount": "number",
"fee_currency": "string",
"payment_amount": "number",
"payment_country": "string",
"payment_currency": "string",
"payment_instruction": "number",
"payment_is_intra": "boolean"
}
This model is a representation of a payment fee.
Fields
Name | Description |
---|---|
fee_amount Always |
Fee amount |
fee_currency Always |
Fee currency |
payment_amount |
Payment amount |
payment_currency Always |
Currency the payment was made in |
payment_country Always |
The destination country of the payment |
payment_instruction Always |
Payment instruction |
payment_is_intra |
True if payment is Ebury intra payments, False otherwise |
Managing Contacts
The Contacts API allows you to amend aspects of the user profiles active on your account.
Get Contacts
GET /contacts?client_id=$client_id HTTP/1.1
Authorization: string
Get all contacts for a given client.
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Response
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"name": "string",
"first_name": "string",
"last_name": "string",
"email_address": "string",
"work_contact_number": "string",
"home_contact_number": "string",
"mobile_contact_number": "string",
"address_line_1": "string",
"address_line_2": "string",
"city": "string",
"country_code": "string",
"country_name": "string",
"post_code": "string",
"password_reset_required": "boolean",
"language": "string",
"locale": "string",
"time_zone": "string",
"has_online_access": "boolean",
"can_authorise_payments": "boolean",
"can_make_same_currency_payments": "boolean",
"can_make_independent_payments": "boolean",
"can_manage_beneficiaries": "boolean",
"can_manage_beneficiaries_groups": "boolean",
"can_manage_contacts": "boolean",
"can_manage_fix_forwards": "boolean",
"can_manage_multipayments": "boolean",
"can_manage_payments": "boolean",
"can_manage_permissions": "boolean",
"can_trade": "boolean",
"contact_id": "string"
}
]
A successful request will return a 200 OK
response with the response body containing a list of Contact objects.
Get a single contact
GET /contacts/$contact_id?client_id=$client_id HTTP/1.1
Authorization: string
Get a single contact by contact ID.
Path Parameters
Parameter | Description |
---|---|
contact_id Required |
The ID of the contact |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "string",
"first_name": "string",
"last_name": "string",
"email_address": "string",
"work_contact_number": "string",
"home_contact_number": "string",
"mobile_contact_number": "string",
"address_line_1": "string",
"address_line_2": "string",
"city": "string",
"country_code": "string",
"country_name": "string",
"post_code": "string",
"password_reset_required": "boolean",
"language": "string",
"locale": "string",
"time_zone": "string",
"has_online_access": "boolean",
"can_authorise_payments": "boolean",
"can_make_same_currency_payments": "boolean",
"can_make_independent_payments": "boolean",
"can_manage_beneficiaries": "boolean",
"can_manage_beneficiaries_groups": "boolean",
"can_manage_contacts": "boolean",
"can_manage_fix_forwards": "boolean",
"can_manage_multipayments": "boolean",
"can_manage_payments": "boolean",
"can_manage_permissions": "boolean",
"can_trade": "boolean",
"contact_id": "string"
}
A successful request will return a 200 OK
response with the response body containing a Contact object.
Update a contact
PATCH /contacts/$contact_id?client_id=$client_id HTTP/1.1
Authorization: string
Content-Type: application/json
{
"language": "string",
"locale": "string",
"time_zone": "string",
"has_online_access": "boolean",
"can_authorise_payments": "boolean",
"can_make_same_currency_payments": "boolean",
"can_manage_beneficiaries": "boolean",
"can_manage_beneficiaries_groups": "boolean",
"can_manage_contacts": "boolean",
"can_manage_fix_forwards": "boolean",
"can_manage_multipayments": "boolean",
"can_manage_payments": "boolean",
"can_manage_permissions": "boolean",
"can_trade": "boolean",
}
Update a single contact identified by contact_id
.
The fields language
, locale
, and time_zone
may be omitted.
If omitted in the API request, the rest of the fields related to permissions will be updated to their default values (which is ‘false’)
Request Headers
Header | Description |
---|---|
Content-Type Required |
application/json |
Path Parameters
Parameter | Description |
---|---|
contact_id Required |
The ID of the contact |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Request Body
Fields
Name | Description |
---|---|
language |
Language expressed as ISO 639-1 two-character code |
locale |
Locale expressed as ISO 639-1 two-character code |
time_zone |
The time zone of the contact |
has_online_access |
Contact has access to Ebury Online |
can_authorise_payments |
Contact can authorise payments |
can_make_same_currency_payments |
Contact can create trades and assign same currency payments |
can_manage_beneficiaries |
Contact can manage beneficiaries |
can_manage_beneficiaries_groups |
Contact can manage beneficiaries groups |
can_manage_contacts |
Contact can manage contacts |
can_manage_fix_forwards |
Contact can manage fixed forwards |
can_manage_multipayments |
Contact can manage multipayments |
can_manage_payments |
Contact can manage payments |
can_manage_permissions |
Contact can manage permissions |
can_trade |
Contact can execute trades |
Response
HTTP/1.1 204 No Content
A successful request will return a 204 No Content
response with an empty response body.
Contact Models
Contact
{
"name": "string",
"first_name": "string",
"last_name": "string",
"email_address": "string",
"work_contact_number": "string",
"home_contact_number": "string",
"mobile_contact_number": "string",
"address_line_1": "string",
"address_line_2": "string",
"city": "string",
"country_code": "string",
"country_name": "string",
"post_code": "string",
"password_reset_required": "boolean",
"language": "string",
"locale": "string",
"time_zone": "string",
"has_online_access": "boolean",
"can_authorise_payments": "boolean",
"can_make_same_currency_payments": "boolean",
"can_make_independent_payments": "boolean",
"can_manage_beneficiaries": "boolean",
"can_manage_beneficiaries_groups": "boolean",
"can_manage_contacts": "boolean",
"can_manage_fix_forwards": "boolean",
"can_manage_multipayments": "boolean",
"can_manage_payments": "boolean",
"can_manage_permissions": "boolean",
"can_trade": "boolean",
"contact_id": "string"
}
This model is a representation of a contact.
Fields
Name | Description |
---|---|
name |
Full name of the contact |
first_name |
First name of the contact |
last_name |
Last name of the contact |
email_address Always |
Email address/username of the contact |
work_contact_number |
The work contact number of the contact |
home_contact_number |
The home contact number of the contact |
mobile_contact_number |
The mobile contact number of the contact |
address_line_1 |
The first address line of the contact |
address_line_2 |
The second address line of the contact |
city |
The city name of the contact |
country_code |
Country as ISO 3166 two-character code |
country_name |
Full name of the country |
post_code |
The postcode of the contact |
password_reset_required |
true if contact needs to reset their password, false otherwise |
language |
Language expressed as ISO 639-1 two-character code |
locale |
Locale expressed as ISO 639-1 two-character code |
time_zone |
The time zone of the contact |
has_online_access |
Contact has access to Ebury Online |
can_authorise_payments |
Contact can authorise payments |
can_make_same_currency_payments |
Contact can create trades and assign same currency payments |
can_make_independent_payments |
Contact can make independent payments |
can_manage_beneficiaries |
Contact can manage beneficiaries |
can_manage_beneficiaries_groups |
Contact can manage beneficiaries groups |
can_manage_contacts |
Contact can manage contacts |
can_manage_fix_forwards |
Contact can manage fixed forwards |
can_manage_multipayments |
Contact can manage multipayments |
can_manage_payments |
Contact can manage payments |
can_manage_permissions |
Contact can manage permissions |
can_trade |
Contact can execute spot trades |
contact_id |
Unique identifier for the Contact |
ContactUpdate
{
"language": "string",
"locale": "string",
"time_zone": "string",
"has_online_access": "boolean",
"can_authorise_payments": "boolean",
"can_make_same_currency_payments": "boolean",
"can_manage_beneficiaries": "boolean",
"can_manage_beneficiaries_groups": "boolean",
"can_manage_contacts": "boolean",
"can_manage_fix_forwards": "boolean",
"can_manage_multipayments": "boolean",
"can_manage_payments": "boolean",
"can_manage_permissions": "boolean",
"can_trade": "boolean",
}
This model is a representation of the updateable data of a contact.
Fields
Name | Description |
---|---|
language |
Language expressed as ISO 639-1 two-character code |
locale |
Locale expressed as ISO 639-1 two-character code |
time_zone |
The time zone of the contact |
has_online_access |
Contact has access to Ebury Online |
can_authorise_payments |
Contact can authorise payments |
can_make_same_currency_payments |
Contact can create trades and assign same currency payments |
can_manage_beneficiaries |
Contact can manage beneficiaries |
can_manage_beneficiaries_groups |
Contact can manage beneficiaries groups |
can_manage_contacts |
Contact can manage contacts |
can_manage_fix_forwards |
Contact can manage fixed forwards |
can_manage_multipayments |
Contact can manage multipayments |
can_manage_payments |
Contact can manage payments |
can_manage_permissions |
Contact can manage permissions |
can_trade |
Contact can execute trades |
Viewing Documents
Get a document
GET /documents?client_id=$client_id&type=$type&id=$id HTTP/1.1
Authorization: string
Get a document for a given client
Query Parameters
Parameter | Description |
---|---|
type Required |
The document type Acceptable values:
|
id Required |
The ID of the entity that generated this document e.g. payment, trade, etc. |
client_id Required |
Your client identifier |
Response
HTTP/1.1 200 OK
Content-Type: text/plain
string
A successful request will return a 200 OK
response with the response body containing a Base 64 encoded string containining the requested document.
Executing Mass Beneficiaries
Submit a Mass Beneficiary instruction
Submit a new mass beneficiary instruction that can be processed in async or sync mode.
Query Parameters
client_id Required |
The ID of the client |
Body Request
The body of the request must contain a list of the Beneficiaries.
POST /mass-beneficiaries?client_id=$client_id HTTP/1.1
Content-Type: application/json
[
{
"name": "string",
"email_addresses": [
"string"
],
"email_notification": "boolean",
"address_line_1": "string",
"street_name": "string",
"state_region": "string",
"building_number": "string",
"floor": "string",
"apartment_office_number": "string",
"post_code": "string",
"country_code": "string",
"account_number": "string",
"bank_address_line_1": "string",
"bank_country_code": "string",
"bank_currency_code": "string",
"bank_identifier": "string",
"bank_name": "string",
"correspondent_account": "string",
"correspondent_swift_code": "string",
"iban": "string",
"inn": "string",
"kbk": "string",
"kio": "string",
"kpp": "string",
"purpose_of_payment": "string",
"reason_for_trade": "string",
"reference_information": "string",
"beneficiary_reference": "string",
"russian_central_bank_account": "string",
"swift_code": "string",
"vo": "string"
}
]
Response
A successful request will return a "202 Accepted" response with the MassBeneficiary model.
Retrieve all Mass Beneficiaries submissions
Obtain the full list of mass beneficiaries async process status for a given client_id. The status field will provide the latest status whether processing is complete or still running.
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client. |
page |
The desired page number for pagination. Default value is 1 . (Coming soon) |
page-size |
The number of items per page for pagination. Default value is 50 . (Coming soon) |
GET /mass-beneficiaries?client_id=$client_id
Response
A successful request will return a "200 OK" response with a list of the Mass Beneficiary objects.
Retrieve a single Mass Beneficiary submission
Retrieve a mass beneficiary resource for a given mass_beneficiary_id. The status field will provide the latest status.
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client. |
mass_beneficiary_id Required |
The unique ID of the mass beneficiary. |
GET /mass-beneficiaries/$mass_beneficiary_id?client_id=$client_id
Response
A successful request will return a "200 OK" response with the Mass Beneficiary Model.
Retrieve errors in beneficiaries creation using Mass Beneficiaries service
View all the errored beneficiaries in a mass beneficiaries instruction.
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client. |
page |
The desired page number for pagination. Default value is 1 . (Coming soon) |
page-size |
The number of items per page for pagination. Default value is 50 . (Coming soon) |
GET /mass-beneficiaries/$mass_beneficiary_id/errors?client_id=$client_id
Response
A successful request will return a "200 OK" response with the response body containing a list of BeneficiaryCreationError objects. In addition, the total number of entries is available in the header field x-total-count.
[
{
"code": "string",
"details": "string",
"message": "string",
"request_index": "number"
}
]
Retrieve successfully created Beneficiaries
View all the created beneficiaries in a mass beneficiaries instruction.
Query Parameters
client_id Required |
The ID of the client. |
page |
The desired page number for pagination. Default value is 1 . (Coming soon) |
page-size |
The number of items per page for pagination. Default value is 50 . (Coming soon) |
GET /mass-beneficiaries/$mass_beneficiary_id/beneficiaries?client_id=$client_id
Response
A successful request will return a "200 OK" response with the response body containing a list of BeneficiaryCreated objects. In addition, the total number of entries is available in the header field x-total-count.
[
{
"beneficiary_id": "string",
"links": {
"beneficiary_href": "/beneficiaries/$beneficiary_id"
},
"request_index": 0
}
]
Mass Beneficiary Models
MassBeneficiary
This model is a representation of a mass beneficiary.
Fields
Name | Description |
---|---|
mass_beneficiary_id Always |
Unique UUID of the mass beneficiary. |
error Always |
The generic error message for the mass beneficiary request, if any. |
links Always |
The MassBeneficiaryLinks. |
summary Always |
The MassBeneficiarySummary. |
status Always |
The MassBeneficiaryStatus. |
{
"mass_beneficiary_id": "uuid",
"error": {
"code": "string",
"message": "string",
"details": "string"
},
"links": {
"errors_href": "/mass-beneficiaries/$mass_beneficiary_id/errors",
"created_href": "/mass-beneficiaries/$mass_beneficiary_id/beneficiaries",
},
"summary": {
"received": "number",
"errored": "number",
"created": "number"
},
"status": "string"
}
MassBeneficiaryStatus
The possible values for the "status" of every mass beneficiary instruction.
Values
Value | Description |
---|---|
pending |
The Mass Beneficiary is pending to be processed. |
creating |
The Mass Beneficiary is being processed. |
created |
The Mass Beneficiary has been successfully processed. |
failed |
The Mass Beneficiary has failed during processing. |
unknown |
The Mass Beneficiary has an unknown status. |
MassBeneficiarySummary
This is an object containing categorized counters for the mass beneficiary.
Fields
Name | Description |
---|---|
received Always |
Total count of received beneficiaries. |
created Always |
Total count of created beneficiaries. |
errored Always |
Total count of errored beneficiaries. |
MassBeneficiaryLinks
This is an object containing links for the mass beneficiary related information. Each link helps the user agent to fetch resources related to errored beneficiaries, and also those created successfully. The mass_beneficiary_id
does not need to be stored as the said resources may be accessed with the provided links.
Fields
Name | Description |
---|---|
errors_href Always |
The link to the errors endpoint /mass-beneficiaries/$mass_beneficiary_id/errors |
created_href Always |
The link to the result endpoint /mass-beneficiaries/$mass_beneficiary_id/beneficiaries |
BeneficiaryCreationError
Creation errors of every beneficiary.
Fields
Name | Description |
---|---|
code Always |
A short code for the error. |
details Always |
Error details. |
message Always |
The error message. |
request_index Always |
The original position of the beneficiary on the submission file. It starts at 0. |
BeneficiaryCreated
Created beneficiaries.
Fields
Name | Description |
---|---|
request_index Always |
The original position of the beneficiary on the submission file. It starts at 0. |
beneficiary_id Always |
The ID of the created beneficiary. |
links Always |
The BeneficiaryCreatedLinks. |
BeneficiaryCreatedLinks
This is an object containing links for the created beneficiary.
Fields
Name | Description |
---|---|
beneficiary_href |
The link to the single beneficiary endpoint /beneficiaries/$beneficiary_id |
Executing Mass Payments
Submit a Mass Payment instruction
Create a new mass payment instruction in async mode only. A mass payment instruction requires either a single sell currency or existing trade ID to be specified in order to create an instruction. Note that within a mass payment instruction it is not possible to use different sell currencies per payment.
Query Parameters
client_id Required |
The ID of the client |
Body Request
The body of the request must contain a list of the objects containing the following fields:
Fields
external_reference_id |
Unique external reference ID submitted by the client. |
auto_commit Always |
If true, and if there are no errors identified at the time of processing the request, the payments will be created. If false, the mass payment process will stop after validation and creation of the beneficiary and will require review/confirmation. |
sell_currency |
Mandatory if no trade_id is provided. |
trade_id |
Mandatory if no sell_currency is provided. |
payment_instructions Always |
Array of Payment Instructions given by the client. |
POST/ mass-payments?client_id=client_id HTTP/1.1
Content-Type: application/json
{
"external_reference_id":"string",
"auto_commit":"boolean",
"sell_currency": "GBP",
"trade_id" :"string",
"payment_instructions": [
{
"account_number":"string",
"bank_address":"string",
"bank_code":"string",
"bank_country":"string",
"bank_name":"string",
"beneficiary_address":"string",
"beneficiary_street_name":"string",
"beneficiary_building_number":"string",
"beneficiary_floor":"string",
"beneficiary_apartment_office_number":"string",
"beneficiary_city":"string",
"beneficiary_state_region":"string",
"beneficiary_post_code":"string",
"beneficiary_name":"string",
"beneficiary_country":"string",
"beneficiary_reference":"string",
"direction":"string",
"external_reference_id":"string",
"iban":"string",
"inn":"string",
"kio":"string",
"payment_currency":"string",
"payment_amount":"number",
"payment_reference":"string",
"purpose_of_payment":"Purpose of Payment",
"reason_for_trade":"string",
"russian_central_bank_account":"string",
"swift_code":"string",
"trade_type":"string",
"value_date":"string",
"vo":"string"
}
]
}
Response
A successful request will return a “202 Accepted” response with the response body containing a list of objects.
Fields
mass_payment_id Always |
Unique UUID of the mass payment. |
external_reference_id Always |
Unique ID of the external reference submitted by the client. |
mass_payment_status Always |
The MassPaymentStatus. |
HTTP/1.1 202 ACCEPTED
{
"mass_payment_id":"uuid",
"external_reference_id":"string",
"mass_payment_status":"string"
}
Retrieve all Mass Payments submissions
Obtain the full list of mass payments async process status for a given client_id. The MassPaymentStatus field will provide the latest status whether processing is complete or still running. API consumers can retrieve a mass payment using an external_reference_id provided at the time of the mass payment submission.
Query Parameters
client_id Required |
The ID of the client |
external_reference_id |
If the same external_reference_id is being used in multiple mass payment requests, then more than one mass payment will be returned. |
sell_currency |
The sell currency of the mass payment ISO 4217. |
page |
The desired page number for pagination. Default value is 1 . |
page-size |
The number of items per page for pagination. Default value is 50 . |
Response
The body of the request must contain a list of the objects containing the following fields:
Fields
mass_payment_id Always |
Unique UUID of the mass payment. |
external_reference_id |
Unique ID of the external reference submitted by the client. |
mass_payment_status Always |
The MassPaymentStatus. |
sell_currency |
The sell currency of the mass payment. |
trades_created |
Total number of created trades. |
payments_summary |
The PaymentsSummaryTypes |
links |
Links to the PaymentsSummaryLinks |
Retrieve a single Mass Payment submission
Obtain a mass payments async process status for a given mass_payment_id. The MassPaymentStatus field will provide the latest status whether processing is complete or still running.
Query Parameters
client_id Required |
The ID of the client |
mass_payment_id Required |
The unique ID of the mass payment. Non mandatory if external-reference-id is provided. |
GET/mass-payments?client_id=client_id&mass_payment_id={mass_payment_id}
Content-Type: application/json
Response
A successful request will return a “200 OK” response with the response body containing a list of MassPayment objects.
Fields
mass_payment_id Always |
Unique UUID of the mass payment. |
external_reference_id |
Unique ID of the external reference submitted by the client. |
mass_payment_status Always |
The MassPaymentStatus. |
sell_currency |
The sell currency of the mass payment. |
trades_created |
Total number of created trades. |
payments_summary |
The PaymentsSummaryTypes |
links |
Links to the PaymentsSummaryLinks |
HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1
[
{
"mass_payment_id":"uuid",
"external_reference_id":"string",
"error": {
"code": "string",
"message": "string",
"details": "string"
},
"mass_payment_status":"string",
"sell_currency":"string",
"trades_created":"number",
"payments_summary":
{
"payments_received":"number",
"payments_processed":"number",
"payments_errored":"number",
"payments_created":"number"
}
"links":
{
"payments_errored_href":"APP_URL/mass-payments/$mass_payment_id/errors?client_id=$client_id",
"payments_created_href":"APP_URL/payments?client_id=$client_id&mass_payment_id=$mass_payment_id",
"trades_href":"APP_URL/trades?client_id=$client_id&mass_payment_id=$mass_payment_id",
"funding_account_href" : "APP_URL/mass-payments/$mass_payment_id/funding-account?client_id=$client_id"
}
}
]
Retrieve payments submitted using Mass Payment service
Obtain all the payment instructions submitted with Submit a Mass Payment Instruction for a given mass_payment_id. You may also filter instructions by payment_currency.
Query Parameters
client_id Required |
The ID of the client |
page |
The desired page number for pagination. Default value is 1 . |
page-size |
The number of items per page for pagination. Default value is 50 . |
payment_currency |
The currency of the payment. |
GET/mass_payments/$mass_payment_id/payments-received?client_id=$client_id
Content-Type: application/json
Response
A successful request will return a “200 OK” response with the response body containing a list of PaymentInstruction objects. In addition, the total number of entries retrieved is available in header field x-total-count.
HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1
[
{
"account_number":"string",
"bank_address":"string",
"bank_code":"string",
"bank_country":"string",
"bank_name":"string",
"beneficiary_address":"string",
"beneficiary_street_name":"string",
"beneficiary_building_number":"string",
"beneficiary_floor":"string",
"beneficiary_apartment_office_number":"string",
"beneficiary_city":"string",
"beneficiary_state_region":"string",
"beneficiary_post_code":"string",
"beneficiary_name":"string",
"beneficiary_country":"string",
"beneficiary_reference":"string",
"direction":"string",
"external_reference_id":"string",
"iban":"string",
"inn":"string",
"kio":"string",
"payment_currency":"string",
"payment_amount":"number",
"payment_reference":"string",
"purpose_of_payment":"Purpose of Payment",
"reason_for_trade":"string",
"russian_central_bank_account":"string",
"swift_code":"string",
"trade_type":"string",
"value_date":"string",
"vo":"string"
}
]
Retrieve errors in payments submitted using Mass Payment service
View all the errored payments in a mass payment instruction possibly by filtering with payment _currency.
Query Parameters
client_id Required |
The ID of the client |
page |
The desired page number for pagination. Default value is 1 . |
page-size |
The number of items per page for pagination. Default value is 50 . |
payment_currency |
The currency of the payment. |
GET/mass-payments/$mass_payment_id/errors?client-id=$client_id
Content-Type: application/json
Response
A successful request will return a “200 OK” response with the response body containing a list of objects. In addition, the total number of entries is available in the header field x-total-count.
Fields
Payment Instruction Always |
Payment Instructions given by the client. |
errors |
Array of objects. Will display the error code and error message. |
HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1
[
{
"account_number":"string",
"bank_address":"string",
"bank_code":"string",
"bank_country":"string",
"bank_name":"string",
"beneficiary_address":"string",
"beneficiary_street_name":"string",
"beneficiary_building_number":"string",
"beneficiary_floor":"string",
"beneficiary_apartment_office_number":"string",
"beneficiary_city":"string",
"beneficiary_state_region":"string",
"beneficiary_post_code":"string",
"beneficiary_name":"string",
"beneficiary_country":"string",
"beneficiary_reference":"string",
"direction":"string",
"external_reference_id":"string",
"iban":"string",
"inn":"string",
"kio":"string",
"payment_currency":"string",
"payment_amount":"number",
"payment_reference":"string",
"purpose_of_payment":"Purpose of Payment",
"reason_for_trade":"string",
"russian_central_bank_account":"string",
"swift_code":"string",
"trade_type":"string",
"value_date":"string",
"vo":"string",
"errors":[
{
"code":"INVALID_VALUE_",
"message":"Invalid Value Date"
}
]
}
]
Confirm a Mass Payment Instruction
Review a processed mass payment and then confirm the instruction to allow trade and payments creation.
You have to confirm a mass payment instruction when 1) The auto_commit field is set to false, 2) The auto_commit field is set to true and errors are identified at the time of processing request.
Query Parameters
client_id Required |
The ID of the client |
POST/mass-payments/{$mass_payment_id}/confirm?client-id=$client_id
Content-Type: application/json
Response
A successful request will return a “202 Accepted” response with the response body containing the mass_payment_status object.
Fields
mass_payment_status Always |
The MassPaymentStatus. |
HTTP/1.1 202 ACCEPTED
Content-Type: application/json
{
"mass_payment_status":"string"
}
Retrieve funding account for trades linked to Mass Payment
Retrieve the funding account where money needs to be deposited for trades created as part of the Mass payment Instruction.
Query Parameters
client_id Required |
The ID of the client |
GET /mass-payments/$mass_payment_id/funding-account
Content-Type: application/json
Response
A successful request will return a “200 OK” response with the response body containing a list of objects.
Fields
account_number |
The funding account number |
bank_identifier |
The funding account bank identifier |
bank_identifier_type |
The funding account bank identifier type |
iban |
The funding account IBAN |
swift_code |
The funding account swift code |
HTTP/1.1 200 OK
Content-Type: application/json
{
"account_number": "93475247",
"bank_identifier": "200605",
"bank_identifier_type": "Sort Code",
"iban": "GB82BARC20060593475247",
"swift_code": "BARCGB22"
}
Mass Payment Model
This model is a representation of a mass payment.
Fields
mass_payment_id |
Unique UUID of the mass payment. |
external_reference_id |
Unique ID of the external reference submitted by the client. |
error |
The generic error message for the mass payment request, if any. |
mass_payment_status |
The MassPaymentStatus. |
sell_currency |
The sell currency of the mass payment. |
trades_created |
Total number of created trades. |
payments_summary |
The PaymentsSummaryTypes |
links |
Links to the PaymentsSummaryLinks |
MassPaymentStatus
The mass_payment_status values of the mass payment instruction.
Values
queued for processing |
The mass payment submission request has been received by Ebury and it has been queued for payment instruction, validation and beneficiary creation. |
processing |
The mass payment request is being processed. PaymentsSummaryTypes will have value=0 because the mass payment instruction validation and beneficiary creation is not yet complete. |
processed |
The payment has been processed. PaymentsSummaryTypes will now contain values (except for payments_created and trade_created which will have value=0) because the payment has not yet reached “created”. |
queued for creating |
The mass payment submission request has been received by Ebury and it has been queued for payment instruction validation and beneficiary creation. |
creating |
The mass payment has been picked up from the queue and it has been submitted for trade and payment creation. PaymentsSummaryTypes will now contain values (except for payments_created and trade_created which will have value=0) because the payment has not yet reached “created”. |
created |
The payment and trade have been created. PaymentsSummaryTypes will now contain relevant values as the process is now complete. Also PaymentsSummeryLinks object will contain a new property funding_account_href. |
PaymentsSummary Types
This is an enumeration of PaymentsSummary types.
Fields
payments_received |
Total count of received payments |
payments_processed |
Total count of processed payments |
payments_errored |
Total count of errored payments |
payments_created |
Total count of created payments |
PaymentsSummary Links
This is an enumeration of PaymentsSummary Links. Each link helps the user agent to fetch resources related to payment errors, payments created successfully, trade and funding accounts associated with the mass payment id. The mass_payment_id does not need to be stored as the said resources may be accessed with the provided links.
Fields
payments_errored_href** |
/mass-payments/$mass_payment_id/errors |
payments_created_href* |
/payments?mass_payment_id=$mass_payment_id |
trades_href* |
/trades?client_id=$client_id&mass_payment_id=$mass_payment_id |
funding_account_href* |
/mass-payments/$mass_payment_id/funding_account |
**Following URL response will return back data when mass_payment_status is "processed" and includes errors.
*Following URL response will return back data when mass_payment_status is "created".
Payment Instructions Model
This is a representation of a payment instruction model. When the Payment Instruction model is used as input, fields marked as REQUIRED are mandatory.
Fields
Name | Description |
---|---|
account_id |
The ID of the beneficiary's bank account. When this is provided, beneficiary details like account number, beneficiary name should not be. |
beneficiary_id |
The ID of the beneficiary. When this is provided, beneficiary details like account number, beneficiary name should not be. |
account_number |
Account number. When this is provided, beneficiary_id, account_id should not be. |
bank_address |
The bank address of the beneficiary. When this is provided, beneficiary_id, account_id should not be. |
bank_code |
The bank code of the beneficiary (UK sort code, US ABA/FedWire, etc.). When this is provided, beneficiary_id, account_id should not be. |
bank_country |
The bank country of the beneficiary in ISO 3166-1 format (two character alpha code). When this is provided, beneficiary_id, account_id should not be. |
bank_name |
Name of the bank account holder. When this is provided, beneficiary_id, account_id should not be. |
beneficiary_address * |
The beneficiary address. When this is provided, beneficiary_id, account_id should not be. (deprecated)* |
beneficiary_street_name * |
The street name of the beneficiary. |
beneficiary_building_number * |
The building number of the beneficiary. |
beneficiary_floor * |
The floor of the beneficiary. |
beneficiary_apartment_office_number * |
The apartment/office number of the beneficiary. |
beneficiary_city *Required |
The city of the beneficiary. |
beneficiary_state_region * |
The state/region of the beneficiary. |
beneficiary_post_code * |
The postcode of the beneficiary. |
beneficiary_country Required |
The beneficiary country in ISO 3166-1 format (two character alpha code). When this is provided, beneficiary_id, account_id should not be. |
beneficiary_name |
The beneficiary name. When this is provided, beneficiary_id, account_id should not be. |
beneficiary_reference |
Permanent reference to add to a beneficiary for all future payments. When this is provided, beneficiary_id, account_id should not be. |
direction Required |
Acceptable values:
|
external_reference_id |
Unique reference submitted by the client to identify the payment. |
iban |
When this is provided, beneficiary_id, account_id should not be. |
inn |
Unique Taxpayer Personal Identification Number for legal entities registered in Russia. |
kio |
Tax ID for foreign legal entities in Russia. |
payment_currency Required |
Buy currency code ISO 4217 |
payment_amount Required |
number |
payment_reference Required |
Payment reference |
purpose_of_payment |
The purpose of payment is mandatory when the beneficiary account has specific currency types. See the section PurposeOfPayment for the currencies and their acceptable values. |
reason_for_trade Required |
Reason for trade. See ReasonForTradeValues for acceptable values. |
russian_central_bank_account |
20-digit code for Russian banks. |
swift_code |
When this is provided, beneficiary_id, account_id should not be. |
trade_type Required |
Type of trade. Acceptable values:
|
value_date Required |
Date of the payment (YYYY-MM-DD) |
vo |
Code of currency transaction established by the Central Bank of Russia to describe the purpose of the payment. |
* This field and the related rule becomes operational from October 2024. Further communication will follow over emails. Please note, it does not apply to Ebury Mass Payments customers in Production.
HTTP/1.1 200 OK
Content-Type: application/json
x-total-count: 1
[
{
"account_number":"string",
"bank_address":"string",
"bank_code":"string",
"bank_country":"string",
"bank_name":"string",
"beneficiary_address":"string",
"beneficiary_street_name":"string",
"beneficiary_building_number":"string",
"beneficiary_floor":"string",
"beneficiary_apartment_office_number":"string",
"beneficiary_city":"string",
"beneficiary_state_region":"string",
"beneficiary_post_code":"string",
"beneficiary_name":"string",
"beneficiary_country":"string",
"beneficiary_reference":"string",
"direction":"string",
"external_reference_id":"string",
"iban":"string",
"inn":"string",
"kio":"string",
"payment_currency":"string",
"payment_amount":"number",
"payment_reference":"string",
"purpose_of_payment":"Purpose of Payment",
"reason_for_trade":"string",
"russian_central_bank_account":"string",
"swift_code":"string",
"trade_type":"string",
"value_date":"string",
"vo":"string"
}
]
*Notes
Example:
At the time of submission of mass-payment (POST /mass-payment) sell_currency field is set as GBP or trade_id provided contains sell_currency as GBP. In the payment instruction payment_currency is set as EUR, payment_amount is set as 100 and direction is set as sell.
{
"auto_commit": "false",
"sell_currency": "GBP",
"external_reference_id": "",
"payment_instructions": [
{
"account_number": "",
"bank_address": "",
"bank_code": "",
"bank_country": "IT",
"bank_name": "",
"beneficiary_address": "",
"beneficiary_street_name": "string",
"beneficiary_building_number": "string",
"beneficiary_floor": "string",
"beneficiary_apartment_office_number": "string",
"beneficiary_city": "string",
"beneficiary_state_region": "string",
"beneficiary_post_code": "string",
"beneficiary_name": "Beneficiary Name",
"beneficiary_country": "IT",
"direction": "sell",
"external_reference_id": "",
"iban": "IT28E0300203280787878415564",
"payment_currency": "EUR",
"payment_amount": 100,
"reason_for_trade": "ben1",
"reference": "reference",
"swift_code": "UNCRITMMXXX",
"value_date": null,
"trade_type": "spot"
}
]
}
In this case the client is giving an instruction to calculate EUR amount equivalent to 100 GBP. The payment_amount will be calculated based on the exchange rate of converting 100 GBP to EUR.
[
{
"account_number": "",
"amount": 116.21,
"authorisation_workflow": "4-eyes",
"authorised_by": null,
"authorised_date": null,
"bank_identifier": "",
"beneficiary_name": "Beneficiary Name",
"cancelled_by": null,
"cancelled_date": null,
"contact_id": "EBPCON36429",
"created_date": "2021-08-20",
"external_reference_id": "",
"fee_amount": 12.85,
"fee_currency": "EUR",
"iban": "IT03V0300203280998885565948",
"invoice_required": false,
"payment_currency": "EUR",
"payment_date": "2021-08-24",
"payment_id": "PI2305652",
"payment_instruction": "/documents?type=pi&id=PI2305652&client_id=EBPCLI00003",
"payment_receipt": "/documents?type=pr&id=PI2305652&client_id=EBPCLI00003",
"reference": "reference",
"rejected_by": null,
"rejected_date": null,
"status": "Validating beneficiary information",
"swift_code": "UNCRITMMXXX",
"trade_id": "EBPOTR2162767"
}
]
Executing Multipayments
Create a multi payment instruction
POST /multipayments?client_id=$client_id&accept_immediately=true HTTP/1.1
Authorization: string
Content-Type: application/json
[
{
"account_number": "string",
"bank_address": "string",
"bank_code": "string",
"bank_country": "string",
"bank_name": "string",
"beneficiary_address": "string",
"beneficiary_street_name": "string",
"beneficiary_building_number": "string",
"beneficiary_floor": "string",
"beneficiary_apartment_office_number": "string",
"beneficiary_city": "string",
"beneficiary_state_region": "string",
"beneficiary_post_code": "string",
"beneficiary_name": "string",
"beneficiary_country": "string",
"beneficiary_reference": "string",
"direction": "string",
"iban": "string",
"inn": "string",
"kio": "string",
"payment_currency": "string",
"payment_amount": "number",
"payment_reference": "string",
"purpose_of_payment": "Purpose of Payment",
"reason_for_trade": "string",
"russian_central_bank_account": "string",
"swift_code": "string",
"trade_type": "string",
"value_date": "string",
"vo": "string"
}
]
Create a new multi payment instruction. Requires either a sell currency or existing trade ID to create the instruction
Request Headers
Header | Description |
---|---|
Content-Type Required |
application/json |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
trade_id |
Trade ID to book payments against. Omit if trade should be executed to fund payments |
sell_currency |
If trade_id omitted, a sell currency must be supplied |
accept_partial |
Accept a partially successful instruction. If true , send successful instructions for payment. If false , reject the entire instruction. Default value is false . |
accept_immediately Required |
Mandatory, set to true . Accept the quote immediately, do not require confirmation. |
Request Body
The body of the request must contain a list of NewMultiPaymentItem.
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"multipayment_id": "integer",
"account_details": {
"account_number": "string",
"bank_identifier": "string",
"bank_identifier_type": "string",
"iban": "string",
"swift_code": "string"
},
"invalid_payments": [
{
"account_number": "string",
"bank_address": "string",
"bank_code": "string",
"bank_country": "string",
"bank_name": "string",
"beneficiary_address": "string",
"beneficiary_street_name": "string",
"beneficiary_building_number": "string",
"beneficiary_floor": "string",
"beneficiary_apartment_office_number": "string",
"beneficiary_city": "string",
"beneficiary_state_region": "string",
"beneficiary_post_code": "string",
"beneficiary_name": "string",
"beneficiary_country": "string",
"beneficiary_reference": "string",
"direction": "string",
"iban": "string",
"inn": "string",
"kio": "string",
"payment_currency": "string",
"payment_amount": "number",
"payment_reference": "string",
"purpose_of_payment": "Purpose of Payment",
"reason_for_trade": "string",
"russian_central_bank_account": "string",
"swift_code": "string",
"trade_type": "string",
"value_date": "string",
"vo": "string"
}
],
"trade_details": [
{
"buy_amount": "number",
"buy_currency": "string",
"client_rate": "number",
"client_rate_symbol": "string",
"inverse_rate": "number",
"inverse_rate_symbol": "string",
"sell_amount": "number",
"sell_currency": "string",
"value_date": "string"
}
]
}
The response will vary depending on whether accept_partial
was set to true
and all the requested payments were created successfully.
If all the payments were created, you will receive a 201 Created
response.
If some of the payments were created, you will receive a 202 Accepted
response.
Both response bodies share a similar model.
Fields
Name | Description |
---|---|
multipayment_id Always |
The multipayment ID |
account_details Always |
The account to which payments should be sent to fund a trade |
account_details.account_number Always |
The account number |
account_details.bank_identifier Always |
The bank identifier |
account_details.bank_identifier_type Always |
The bank identifier type (UK sort code, US ABA/FedWire, etc.) |
account_details.iban |
The account IBAN |
account_details.swift_code |
The account SWIFT code |
invalid_payments |
A list of payments that were not created, using the same model as the request |
trade_details Always |
The trade details |
trade_details.buy_currency Always |
Buy currency code |
trade_details.buy_amount Always |
Buy amount |
trade_details.client_rate Always |
Trade rate |
trade_details.client_rate_symbol Always |
The symbol of the rate |
trade_details.sell_currency Always |
Sell currency code |
trade_details.sell_amount Always |
Sell amount |
trade_details.inverse_rate Always |
The inverse rate |
trade_details.inverse_rate_symbol Always |
The symbol of the inverse rate |
trade_details.value_date Always |
Value date |
Accept a multi payment
PATCH /multipayments/$multipayment_id?client_id=$client_id HTTP/1.1
Authorization: string
Content-Type: application/json
Accepts the trades generated during the multi payment initiation and also books the associated payments.
Request Headers
Header | Description |
---|---|
Content-Type Required |
application/json |
Path Parameters
Parameter | Description |
---|---|
multipayment_id Required |
The multi payment ID |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"account_number": "string",
"bank_identifier": "string",
"bank_identifier_type": "string",
"iban": "string",
"swift_code": "string"
}
A successful request will return a 200 OK
response with the following response body.
Fields
Name | Description |
---|---|
account_number Always |
The account number |
bank_identifier Always |
The bank identifier |
bank_identifier_type Always |
The bank identifier type (UK sort code, US ABA/FedWire, etc.) |
iban |
The account IBAN |
swift_code |
The account SWIFT code |
Reject a multi payment
DELETE /multipayments/$multipayment_id?client_id=$client_id HTTP/1.1
Authorization: string
Rejects the trades generated during the multi payment initiation and also cancels the associated payments.
Path Parameters
Parameter | Description |
---|---|
multipayment_id Required |
The multi payment ID |
Query Parameters
Parameter | Description |
---|---|
client_id Required |
The ID of the client |
Response
HTTP/1.1 204 No Content
A successful request will return a 204 No Content
response with an empty response body.
Multipayment models
NewMultiPaymentItem
Every payment instruction to be submitted.
Fields
Name | Description |
---|---|
account_number Required |
Account number |
bank_address Required |
The bank address of the beneficiary |
bank_code Required |
The bank code of the beneficiary (UK sort code, US ABA/FedWire, etc.) |
bank_country Required |
The bank country of the beneficiary in ISO 3166-1 format (two character alpha code) |
bank_name Required |
Name of the bank account holder |
beneficiary_address * |
The beneficiary address (deprecated)* |
beneficiary_street_name * |
The street name of the beneficiary. |
beneficiary_building_number * |
The building number of the beneficiary. |
beneficiary_floor * |
The floor of the beneficiary. |
beneficiary_apartment_office_number * |
The apartment/office number of the beneficiary. |
beneficiary_city *Required |
The city of the beneficiary. |
beneficiary_state_region * |
The state/region of the beneficiary. |
beneficiary_post_code * |
The postcode of the beneficiary. |
beneficiary_country Required |
The beneficiary country in ISO 3166-1 format (two character alpha code) |
beneficiary_name Required |
The beneficiary name |
beneficiary_reference |
Permanent reference to add to a beneficiary for all future payments. |
direction Required |
Acceptable values:
|
iban Required |
|
inn |
Unique Taxpayer Personal Identification Number for legal entities registered in Russia. |
kio |
Tax ID for foreign legal entities in Russia. |
payment_currency Required |
Buy currency code |
payment_amount Required |
number |
payment_reference Required |
Payment reference |
purpose_of_payment |
The purpose of payment is mandatory when the beneficiary account has specific currency types. See the section PurposeOfPayment for the currencies and their acceptable values. |
reason_for_trade Required |
Reason for trade. See ReasonForTradeValues for acceptable values. |
russian_central_bank_account |
20-digit code for Russian banks. |
swift_code Required |
|
trade_type Required |
Type of trade. Acceptable values:
|
value_date Required |
Date of the payment |
vo |
Code of currency transaction established by the Central Bank of Russia to describe the purpose of the payment. |
* This field and the related rule becomes operational from October 2024. Further communication will follow over emails. Please note, it does not apply to Ebury Mass Payments customers in Production.
Webhook notifications
Practically speaking, a webhook is a POST request to a url of your choice, triggered by an internal event of a remote service. The benefit of webhooks is to receive desired type of notifications to your systems from remote services without regular polling.
The Ebury Events System Webhooks API allows you to add your subscriptions (i.e. HTTP endpoints) to receive Events Systems' notifications.
Usage
# 1. GraphQL query
{
subscriptions {
nodes {
clientId
contactId
}
}
}
# 2. Corresponding HTTP request
POST /webhooks/graphql HTTP/1.1
Authorization: Bearer $access_token
Content-Type: application/json
X-Client-ID: $client_id
{
"query": "{ subscriptions { nodes { clientId contactId } } }"
"variables": {}
}
The Webhooks API is using GraphQL.
This means that your queries will look like this:
- in GraphQL (example #1)
- as an HTTP POST request (example #2)
Your already existing infrastructure can be used to send HTTP requests as usual, and the response will be serialized as JSON data. In addition, detailed data schema information is also provided, helpful to improve tooling on your side.
Notification History
Every notification attempt is stored on our side. On top of the notification details, we also store the status code, headers and body returned by your subscription in response.
Notifications history, including failed attempts will be available for you to review anytime.
Authentication
Authentication is managed as usual for Ebury API services.
You have to provide Authorization: Bearer $access_token
as described in the Authentication chapter.
Please note that the client_id
parameter is still mandatory. However it could be provided in two different ways.
- as a query parameter (as usual)
- as an
X-Client-ID
HTTP header field
We are allowing for this second option in order to be more respectful with the GraphQL standards (see: Webhooks Examples).
GraphQL: differences from REST
You can think of the Webhooks API as any traditional (REST) API. However having said that, if you want to make use of a better user experience you may want to consider the following resources:
- The Webhooks API is following the GraphQL specs
- Each endpoint supports Schema Introspection. This allows you to validate your queries, determine the type of result data, etc.
- Pagination goes according to the Relay Cursors Connections Specification. (Consistent pagination and ordering via cursors.)
The Webhooks API has one single endpoint (/webhooks/graphql
), supporting uniquely POST requests. Due to this reason, interacting with the API is a bit different from what you may be used to.
(The Webhooks Examples section should help you to get used to required payloads.)
Retrieving information
{
"query": "{\n clientId\n contactId\n}",
"variables": {}
}
Instead of GET queries, now we will have to send a POST request when aiming to retrieve information.
The JSON payload requires two fields
query
: the query as a stringvariables
(optional): further information to be passed with the request, as a JSON dictionary.
Add/modify/delete
{
"query": "mutation deleteSubscription($id: UUID!){deleteSubscription(input: {id: $id }) {}}",
"variables": {
"id": "c9f8f293-3391-4cc7-9a97-cb0e26d901e9"
}
}
GraphQL allows for data modifications via internal objects called mutations
, referring to GraphQL functions on the Webhooks API database.
A number of mutation functions belong to each data structure, one for each data manipulation action (create, update, delete).
Your HTTP request has to refer to the one specific to your needs. The JSON payload will require
query
field- embedding the
mutation
function signature- embedding the mutation function data
- embedding the
variables
: potential variables
Error Reporting
The returned HTTP response may (or may not) contain an error
entry. This is a non-empty list of errors, thus only shipped when errors were encountered.
Each entry in the errors
list is a map, containing a message
string field. Please note that the message is intended for the developer.
(see GraphQL Errors Specification).
Great developer tools
Note: This feature is not yet fully available in the initial Webhooks API release. However you may find it useful despite the limited functionality.
As a part of the Webhooks API, an interactive GraphiQL interface is available (at the Webhooks API url root), which facilitates the construction of request payloads enormously.
It allows you to write and execute your queries live, get a description of functionalities available for the schema (with detailed help messages on each), provides embedded text completion for writing syntactically valid queries etc.
Especially in case you are new to GraphQL we strongly recommend you to take a look at this feature. It allows for an easy and natural introduction to the GraphQL syntax. It is extremely helpful, intuitive, self-explaining... and fun.
Securing your webhooks
Ebury will put a signature in every HTTP request sent so you can verify if you can trust the payload. The header X-Ebury-Signature
will contain the sha3 HMAC hexdigest of the URL concatenated with the body payload. The secret
to be used as key in the HMAC computation can be stored and retrieved alongside other fields of the subscription. If you don't set a secret
, the empty string will be used as a key.
For an url url
, body body
and a secret secret
, you can expect a header X-Ebury-Signature
to be exactly sha3-256=52cecc9451d6279c3ef1d345c76edb320782203f876d19396fc9baeafbcbf81f
.
Webhooks Traceability
To simplify the developer experience, a contact can subscribe several clients to the same url.
If this is the case, you will need that the webhook receiver can identify which client is the stakeholder of a particular call.
You can do that by checking the value of the header X-Ebury-Client-Id
.
Webhooks Types
Ebury supports several types of events, which you can see in the table below. You can subscribe to one specific event or to
all of them.
In every webhook POST call, you will receive a JSON payload as body.
You can identify which type of notification you are receiving, by checking the X-Ebury-Webhook
header.
Query all types
You can get a list of all currently supported types by using the custom function webhookTypes.
{
webhookTypes
}
POST /webhooks/graphql HTTP/1.1
Authorization: Bearer $access_token
Content-Type: application/json
X-Client-ID: $client_id
{
"query": "{\n webhookTypes\n}",
"variables": {}
}
HTTP/1.1 200 OK
Server: nginx/1.13.10
Date: Thu, 10 Sep 2020 19:03:27 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 196
Connection: close
X-GraphQL-Event-Stream: /graphql/stream
{
"data": {
"webhookTypes": [
"TRADE_STATUS_CHANGE",
"PAYMENT_STATUS_CHANGE",
"CREDIT_INCOMING_TRANSACTION",
"CREDIT_MARGIN_TRANSACTION",
"CREDIT_PAYMENT_RETURNED_TRANSACTION",
"CREDIT_TRANSACTION",
"DEBIT_TRANSACTION",
"ONBOARDING_STATUS_CHANGE"
]
}
}
List of types
This is the current (growing) list of notifications you can receive using the Webhooks API.
Notification | X-Ebury-Webhook |
Type |
---|---|---|
Status change on Trades created by the client. | TradeStatusChange |
TRADE_STATUS_CHANGE |
Status change on Payments created by the client. | PaymentStatusChange |
PAYMENT_STATUS_CHANGE |
Incoming funds into client's account. | CreditIncomingTransaction |
CREDIT_INCOMING_TRANSACTION |
Margin credited back into client's account. | CreditMarginTransaction |
CREDIT_MARGIN_TRANSACTION |
Returns of the payments the client initiated. | CreditPaymentReturnedTransaction |
CREDIT_PAYMENT_RETURNED_TRANSACTION |
Credit is made to a client's account. | CreditTransaction |
CREDIT_TRANSACTION |
Debit is made to a client's account. | DebitTransaction |
DEBIT_TRANSACTION |
Status change when onboarding new client | OnboardingStatusChange |
ONBOARDING_STATUS_CHANGE |
TradeStatusChange
{
"data":
[
{
"beneficiaries": [],
"rate_symbol": "EURGBP",
"trade_id": "EBPOTR002781",
"buy_currency": "EUR",
"fee_amount": 0.0,
"parent_trade_id": null,
"status": "Created",
"trade_receipt": "/documents?type=tr&id=EBPOTR002781&client_id=EBPCLI00004",
"rate": 0.935057,
"order_date": "2020-06-29",
"maturity_date": "2020-06-29T20:00:00.00Z",
"sell_currency": "GBP",
"reference": "",
"fee_currency": "GBP",
"synthetic": false,
"sell_amount": 935.06,
"trade_type": "spot",
"buy_amount": 1000.0
}
]
}
This model is a representation of the webhook for a status change on a trade.
Fields
Name | Description |
---|---|
data Always |
A list of BookedTrade |
PaymentStatusChange
{
"data":
[
{
"account_number": "",
"amount": 6.02,
"authorisation_workflow": "4-eyes",
"authorised_by": null,
"authorised_date": null,
"bank_identifier": "",
"beneficiary_name": "Homer Simpsons S.L.",
"cancelled_by": null,
"cancelled_date": null,
"contact_id": "EBPCON00005",
"created_date": "2020-07-14",
"fee_amount": 12.85,
"fee_currency": "EUR",
"iban": "GB81KMWJ48036895317360",
"invoice_required": false,
"payment_currency": "GBP",
"payment_date": "2020-07-15",
"payment_id": "PI02488",
"payment_instruction": "/documents?type=pi&id=PI02488&client_id=EBPCLI00004",
"payment_receipt": "/documents?type=pr&id=PI02488&client_id=EBPCLI00004",
"reference": "Development services",
"rejected_by": null,
"rejected_date": null,
"status": "Validating beneficiary information",
"swift_code": "GBGBGBGB",
"trade_id": "EBPOTR002772"
},
],
"payment_webhook_status": ["CREATED"]
}
This model is a representation of the webhook for a status change for a payment.
Fields
Name | Description |
---|---|
data Always |
A list of Payment |
payment_webhook_status Always |
A list of PaymentWebhookStatus |
CreditTransaction
{
"data":
[
{
"account_id": "c18a42df-6652-d462-351b-0485a6d6bc16",
"additional_transaction_information": "EURGBP 0.876804 - other",
"amount": {
"amount": "100.00",
"currency": "EUR"
},
"balance": {
"amount": {
"amount": "50212.85",
"currency": "EUR"
},
"type": "InterimAvailable",
"credit_debit_indicator": "Credit"
},
"booking_datetime": "2019-11-11T20:37:30.598",
"credit_debit_indicator": "Credit",
"status": "Booked",
"transaction_id": "3ae5b450-1e1a-b116-1fde-3cb4f0353e16",
"transaction_information": "Bought EUR EBPOTR002772",
"transaction_reference": "EBPOTR002772",
"value_datetime": "2019-11-11T20:37:30.598",
"creditor_name": "Jorge Chapa",
"creditor_account": {
"account_name": "EBURY OFFICE ACC CHF",
"account_number": "",
"bank_identifier": "",
"bank_identifier_code": "",
"iban": "GB78BARC12345678901234",
"swift": ""
},
"debtor_name": "Jorge Corp",
"debtor_account": {
"account_name": "Cool Account",
"account_number": "1234567890",
"bank_identifier": "123456",
"bank_identifier_code": "",
"iban": "",
"swift": "RACZHUH1123"
}
}
]
}
This model is a representation of the webhook for a credit transaction.
Fields
Name | Description |
---|---|
data Always |
A list of Transaction |
Payment Webhook Status
Status of the payment's webhook
Values
Value | Description |
---|---|
CREATED |
Payment has been created. |
PENDING_OF_AUTHORIZATION |
Payment is waiting for authorization. |
AUTHORIZED |
Payment has been authorized. |
REJECTED |
Payment has been rejected. |
CANCELLED |
Payment has been cancelled. |
SENT |
Payment instruction sent to payment scheme. |
PENDING_RETURN |
Payment is pending return. |
RETURNED |
Payment has been returned. |
INVALIDATED |
Payment has been invalidated. |
OnboardingStatusChange
Will give notification about the change of status during onboarding a client. Example of onboarding message is on a side, more information about onboarding can be found on onboarding documentation
{
"data": [
{
"type": "onboardingRequest",
"links": {
"self": "/provision/v2/onboarding/0013N00000CAZrWQAX"
},
"id": "0013N00000CAZrWQAX",
"attributes": {
"OnboardingStatus": "Client Onboarded",
"AccountNumber": "455053",
"EburyId": "ECECLI455053",
"BecameClient": "2020-04-01"
}
}
]
}
Webhook Examples
Scenarios presented in this section should be considered as examples. Feel free to modify them to better fit your needs.
Most of the examples will only contain the GraphQL query. As explained earlier, this becomes the string value of the query
field in the HTTP POST request payload .
When you create your subscription you should specify which type of notification you are interested in. You can always change it by patching the subscription.
As a reminder, the first example includes both the query and the related HTTP request.
Create a subscription
mutation {
createSubscription(input: {
subscription: {
active: true
secret: "secret"
url: "https://httpbin.org/post"
types: [TRADE_STATUS_CHANGE]
}
}) {
subscription {
id
}
}
}
POST /webhooks/graphql HTTP/1.1
Authorization: Bearer $access_token
Content-Type: application/json
X-Client-ID: $client_id
{
"query": "mutation createSubscription{\n createSubscription(\n input: {\n active: true\n secret: \"secret\"\n url: \"https://httpbin.org/post\"\n types: [TRADE_STATUS_CHANGE]\n }\n ) {\n subscription {\n id\n }\n }\n}",
"variables": {}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 94
Connection: close
Date: Mon, 13 Apr 2020 11:19:09 GMT
{
"data": {
"createSubscription": {
"subscription": {
"id": "c7677669-8dd6-4deb-923c-c38eb6b65789"
}
}
}
}
In order to receive notifications, the first step is to create a subscription.
Make sure to only include active: true
in the payload if you want to receive notifications right after creation. Otherwise you can enable the subscription later.
Once a subscription is active, notifications related to the client will be sent to the specified URL.
Note that the secret
is optional and will be used as a key to sign the payload.
Note that the types
must be present and will specify which type of notification you want to receive.
If you are not sure which types of notification you want to receive you can specify all of them and update them later on by patching the subscription.
As mentioned earlier, we will have to use a so-called mutation
. The corresponding GraphQL function is createSubscription
, requiring subscription URL and status as parameters.
- GraphQL query (example snippet #1)
- The query embedded into a HTTP request payload (example #2)
- The HTTP response object (example #3)
Ping a subscription
POST /webhooks/ping/c7677669-8dd6-4deb-923c-c38eb6b65789 HTTP/1.1
Authorization: Bearer $access_token
Content-Type: application/json
X-Client-ID: $client_id
HTTP/1.1 204 No Content
If you need to check the connectivity of a subscription, even if it is disabled, you can send a ping event.
To do that, you only need to POST
, with all the usual headers, the path /webhooks/ping/:subscription_id:
.
This endpoint does not require a body as input and neither does it return anything: it is only a POST
call that will generate a 204
response.
Calling the endpoint will generate a ping event to simulate the workflow of a regular webhook, triggering a notification for the configured URL.
The Ping
webhook is a special one since it is sent to specific subscriptions.
You can expect the communication between this API and your webhook receiver to follow the same rules as other types of webhooks.
The header X-Ebury-Client-Id
will be populated, and X-Ebury-Webhook
will contain the special value Ping
.
The payload will be a valid json
without any specific schema, apart from being signed in X-Ebury-Signature
as usual.
Get the list of subscriptions
{
subscriptions {
totalCount
nodes {
id
createdAt
url
active
types
}
}
}
{
subscriptions(filter: {
active: {
equalTo: true
}
}) {
totalCount
nodes {
id
createdAt
url
active
types
}
}
}
Two example usages, to
- query the list of all subscriptions (example #1),
- or filter only for the active ones (example #2),
Delete a subscription
mutation deleteSubscription($id: UUID!){
deleteSubscription(
input: {
id: $id
}
) {
subscription {
id
}
}
}
{
"id": "c9f8f293-3391-4cc7-9a97-cb0e26d901e9"
}
POST /webhooks/graphql HTTP/1.1
Authorization: Bearer $access_token
Content-Type: application/json
X-Client-ID: $client_id
{
"query": "mutation deleteSubscription($id: UUID!){\n deleteSubscription(\n input: {\n id: $id\n }\n ) {\n subscription {\n id\n }\n }\n}",
"variables": {
"id": "c9f8f293-3391-4cc7-9a97-cb0e26d901e9"
}
}
To delete a subscription you will need to send a mutation
object, invoking the deleteSubscription
GraphQL function.
In this example, we create a query with an input variable, and then we send the value of the variable.
To make it easier to follow, we include
- GraphQL query and internal variable definition (example #1a + #1b)
- HTTP request with all embedded in the payload (example #2)
Enable a subscription
mutation enableSubscription($id: UUID!){
updateSubscription(
input: {
id: $id
patch: {
active: true
}
}
) {
subscription {
id
active
}
}
}
{
"id": "c9f8f293-3391-4cc7-9a97-cb0e26d901e9"
}
If you want to change the status (active
property) of a subscription, you need to apply a mutation
invoking the updateSubscription
GraphQL function.
Disable a subscription
mutation disableSubscription($id: UUID!){
updateSubscription(
input: {
id: $id
patch: {
active: false
}
}
) {
subscription {
id
active
}
}
}
{
"id": "c9f8f293-3391-4cc7-9a97-cb0e26d901e9"
}
Disabling a subscription goes just the same.
Get the last notification of every subscription
{
subscriptions {
nodes {
active
createdAt
id
url
types
notifications(first:1, orderBy:CREATED_AT_DESC) {
totalCount
nodes {
id
createdAt
body
attempts {
totalCount
}
}
}
}
}
}
The power of GraphQL relies on the ability to navigate across data relationships.
This will allow us to efficiently retrieve a list of subscriptions, with the latest notification belonging to each.
Note that we are using a combination of two options to get the latest notification.
orderBy
attribute making sure that the first notification attempt is the newestfirst: 1
: to get no more but the first (one) notification attempt
Patch a subscription
Patching a subscription is a useful way to change the scope of your notification by changing the types of event you are interested in. When you are not sure which types of events are important for you, you can subscribe for all and then unsubscribe undesired events by patching your subscription. When changing the types, you need to specify the whole new list of types.
Few examples of patching your type values:
types: []
subscribe to none types of events, will have similar effect like disable the subscription by setting Active to False.types: [TRADE_STATUS_CHANGE, PAYMENT_STATUS_CHANGE, CREDIT_INCOMING_TRANSACTION, CREDIT_MARGIN_TRANSACTION, CREDIT_PAYMENT_RETURNED_TRANSACTION, ONBOARDING_STATUS_CHANGE, CREDIT_TRANSACTION, DEBIT_TRANSACTION]
subscribe to all types of eventstypes: [TRADE_STATUS_CHANGE, CREDIT_INCOMING_TRANSACTION]]
subscription to only 2 events type
mutation updateSubscription($id: UUID!, $url: String!, $types: [WebhookType!]){
updateSubscription(
input: {
id: $id
patch: {
url: $url
types: $types
}
}
) {
subscription {
id
url
active
types
}
}
}
{
"id": "ad1e5009-2a8e-44c9-922f-b7da22f66325",
"url": "https://example.com/",
"types": ["TRADE_STATUS_CHANGE", "CREDIT_INCOMING_TRANSACTION"]
}
If you want to change the url and event types of a subscription, you need to update it as such:
Responses
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 94
Connection: close
Date: Mon, 13 Apr 2020 11:19:09 GMT
{
"data": {
"createSubscription": {
"subscription": {
"id": "c7677669-8dd6-4deb-923c-c38eb6b65789"
}
}
}
}
Success
A successful request will return a 200 OK
response with a map.
This map will include an entry with
- a
data
field- that will further include the requested operation
- that will further include fields that were requested for the response.
- that will further include the requested operation
Failure
See Error Reporting for details of unsuccessful requests.