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.
The Consumers APIs allows you to create a new consumer and add its profile data.
These API also allows you to put any changes about your consumers, such as address details change, status changes or etc.
Pay in’s to consumer’s accounts from payment counterparties
The Collection Payments APIs are designed to manage existing inward payments. Since an inward payment collection is subject to your Partnering Bank selection, not all of the endpoints may be availble.
Pay out’s from consumer’s accounts to payment counterparties
The Payout APIs are desgined to perform outward payment operations from your customer’s accounts to a created Counterparty (for more information please refer to Counterparty APIs).
Payment between two different consumer accounts. These includes both payments between two different consumers as well as the movement of funds across single consumer’s accounts
The Intenral Payments APIs allow to you to perform a range of various payments. These API endponts could be used to perform:
Payments between a single customer accounts;
Payments between your customers;
Payments between your company and your customers, in order to:
Take a commission or fee; or
Give a bonus, loan or etc.
To make an internal payment you should have two different account id’s present in your request body. The requests are only processed should two accounts specified have the same currency.
Currency Exchange (CE) These are the payments which are made in order to convert one form of currency into another within one single wallet
Endpoint Group Description - text explaining the API group purpose
The Card Payments APIs are designed to provide you with the ability of viewing and managing your issued cards authorisations and past transactions.
The Currency Exchange API allows you to retrieve the lates FX market rates as set during your setup stage and pass any currency exchange operations together with that FX rate. Currency Exchange APIs also allows you to retrieve your latest open currency position.
When your system is configured you can use these endpoints to get market FX rates. These rates can be used to perform currency exchange operations described here.
Obtain model of and data of product
Endpoint Group Description - text explaining the API group purpose
Obtain models of form, request and data of subscription
Endpoint Group Description - text explaining the API group purpose
The client requests an access token by authenticating with the authorization server and presenting the authorization grant
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:
For more information about our Developer’s Portal please visit our website www.elcoin.co.uk/developer.
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.