The Elcoin API is designed to be flexible and give you control in how and when you control consumers (your customers) data, convert currencies, make payments and manage accounts.
We recommend you read through the API Documentation in full to familiarise yourself with the features and workflows associated with the product. Demo account access can also be provided to you, and the Client ID and API key can be generated within Account settings > API keys in the Web Application.
For any assistance through the integration, your Elcoin Support Manager and your allocated Elcoin Business Success Manager will be able to help guide you.
Below is a brief description of each of our current endpoints.
With Elcoin ABS API you can get the access to our core and concentrate only on designing you products and services.
To access your Elcoin ABS sandbox you should follow these basic steps:
1. Create your profile at www.elcoin.co.uk
2. Request your sandbox API key via our Developer’s Portal
3. Plug in your API key into your tech and start fun!
For more information about our Developer’s Portal please visit our website www.elcoin.co.uk
This section describes the data types and formats used consistently in the API.
| Name | Data Type | Description |
|---|---|---|
| Dates | String() | Dates (without time/timezone information) in YYYY-MM-DD format. Sample use cases: conversion_date, payment_date. |
| Timestamps | String() | Date and time with timezone information in YYYY-MM-DDTHH:mm:ssZ format. Sample use cases: settlement_cutoff_time, created_at, last_updated_at. |
| Country Codes | String() | Two-letter ISO 3166-2 country codes. |
| Currency Codes | String() | Three-letter ISO 4217 currency codes. |
| Langauge Codes | String() | Two-letter ISO 639-1:2002 language codes. |
| Name | Example |
|---|---|
| Date | 2021-03-26 |
| Timestamp | 2021-03-26T16:30:00+1100 |
| Country Code | AU |
| Currency Code | AUD |
| Langauge Code | EN |
Elcoin ABS uses conventional HTTP response codes to indicate the success or failure of an API request. Typically a status code in the 2xx range indicates success, status codes in the 4xx range indicate an error that has been triggered due to the information provided (for example; a parameter does not meet the validation requirements or was not provided), and status codes in the 5xx range indicate an error with our servers.
When we send an error response, the body will generally contain the following fields:
| Name | Data Type | Description |
|---|---|---|
| Code | String() | Error code (please refer to reference table). |
| Source | String() | Name of the request parameter that caused the error. |
| Message | String() | Description of the error. |
| Code | Description |
|---|---|
| 200 | OK - The request was processed successfully. |
| 201 | Created - The request was processed successfully. |
| 400 | Bad request - The request contains missing parameters, is in an incorrect shape, or failed another validation test. |
| 401 | Unauthorised - Please verify that the authentication token is provided and is valid. |
| 404 | Not found - The requested endpoint does not exist. |
| 500 | Server error - Something went wrong on our end; please let us know if you are receiving this error. |
| Error Code | Description |
|---|---|
| amount_above_limit | The amount requested exceeds the maximum payment or conversion limit. |
| amount_above_payment_method_limit | The amount requested exceeds the maximum limit for this payment method and country. |
| amount_below_limit | The amount requested falls below the minimum payment or conversion limit. |
| can_not_be_edited | The payment is being processed and therefore can no longer be edited. |
| conversion_create_failed | The conversion was not created for an unknown reason, for example due to a third-party error. |
| credentials_expired | The authorisation credentials have expired; new credentials should be requested. |
| credentials_invalid | The authorisation credentials are not valid or have been invalidated; new credentials should be requested. |
| field_required | A mandatory field in the request is missing. |
| invalid_argument | A provided argument has an incorrect type or failed a validation test. |
| invalid_currency_pair | The currency pair not valid; such as when the buy_currency is equal to the sell_currency. |
| invalid_payment_date | The payment date cannot be chosen because it falls on a holiday/non-business day of at least one of the countries involved. |
| invalid_conversion_date | The conversion date cannot be chosen because it falls on a holiday/non-business day of at least one of the countries involved. |
| service_unavailable | The requested service is currently unavailable due to operating hours limitations, or because a third-party service is temporarily unavailable. |
| term_agreement_is_required | Agreement to the terms of service is required and must be provided as a true boolean. |
| too_many_requests | Too many requests are received too quickly. |
| unsupported_country_code | Payments to (or payments from) the requested country is currently not supported. |
| unsupported_currency | Conversion to (or conversion from) from the requested currency is currently not supported. |
| unsupported_payment_method | The payment method chosen is not available for the selected beneficiary bank country and payment currency. |
{ "code": "invalid_argument", "source": "first_name", "message": "Value is too short" }Elcoin ABS uses versioning to improve our API contracts without affecting existing users.
When we need to introduce a backwards-incompatible change, such as renaming or splitting a field, we will create a new date version which clients can migrate to when ready.
The latest version is ????-??-??.
Your version is stored in your account and automatically applied to your API calls.
Please log in to view your version.
You may override this version on a per call basis by setting the x-api-version header. This should only be used in exceptional cases, such as when testing and migrating to a newer version, or when calling on behalf of another account.
Refer to Change Log below to see what contract changes the new version introduces. You can also view the full documentation for a chosen version using the dropdown within the menu.
Development: Set the x-api-version header to the newer version on affected endpoints. Modify your code as per the new API contracts.
Test & release: Test the changes in our demo environment, then release to production. You may also use feature flagging to incrementally migrate traffic.
Change account version: Once your production traffic is migrated to the newer version via the x-api-version header, notify our support team and we'll update your account to the newer version. Shortly (> 1hr) after this you may remove the x-api-version header from your API calls.
The following are examples of backwards-compatible changes:
Adding new API endpoints
Adding new optional fields to request models
Adding new fields to response models
Adding new required fields to request models where the change relates to a new payment corridor or method
Modifying content of unstructured text fields, such as error messages and field labels
We regularly introduce such backwards-compatible changes to our API to support new product features. These should not affect existing integrations so we can introduce them directly to all versions. This avoids clients having to upgrade to a newer version to utilise the new functionality. Please ensure your integration supports these changes, e.g. disable checks on unknown fields in the response.
Changes other than these may be either of the following:
Backwards-incompatible change: these are changes to our API contracts which we can use versioning to avoid existing client impact.
External data requirement change: see question below.
Occasionally, regulators or third-party service providers may mandate additional data requirements for existing functionality. In these cases we will need to enforce the requirement for all clients who use the affected functionality. To minimise impact, we will likely introduce the third-party change requirement to all versions (to avoid needing to do a large upgrade to latest version). This situation has not yet arisen; if/when it does we will be in contact with full details.
The URL version is expected to stay as "v1" for the foreseeable future. However, it may be used at a later date for a complete API overhaul, such as migrating REST to GraphQL.
The following lists backwards-incompatible versions of Elcoin ABS API.
It includes a list of all affected endpoints to assist in identifying any migration work required. Please refer to the relevant version's documentation for full details of each affected endpoint's new contract.
If you have further questions or concerns please contact our support team.
Log Structure
Every log change is recorded by our team as follows:
Date - the date when the change was recorded;
Change Description - the exact functional section which was affected and notes how it was adjusted.
Impacted URLs - the list of URLs which have been affected as the result of the change.