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

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.

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

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

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

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.

Where a customer has multiple identifiers the correct one will need to be selected by your application prior to making an API call.

Book a Trade

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.

Note: The trade needs to be funded using the account details contained in the book trade response.

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

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

Add a Beneficiary

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.

Note: Whilst the beneficiary exists and payments can be booked against the beneficiary must past compliance before payments can actually proceed.

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

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
}

Make a Payment

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.

Note: For bulk operations, Multi Payments wraps the functionality of quote, trade, beneficiary, and payment into a simple call. See relevant section for more details.

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

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

​Get a Quote

​Client Identifier

​Book a Trade

​Add a Beneficiary

​Make a Payment

Get a Quote

Client Identifier

Book a Trade

Add a Beneficiary

Make a Payment