Welcome to the ONE API documentation. The guidance provided here is specifically designed to provide you with access to our global payments platform, allowing you to move money seamlessly around the world via our network of global banking partners.
ONE Group was established in 2017 to provide a one-stop financial services solution to pioneers within high-risk industries across its crypto-trading and global multi-bank payments platform.
Supported destinations and currencies The section shows payments in which currencies and in which destinations are available from which types of accounts.
Work with accounts The section describes the types of accounts within ONE, and how to address them while working with the API.
Payment types and transfers The section describes categories of payments and transfers within ONE, and how to choose the best for your task.
How to query Transaction history A scenario for getting transactions history for an account.
How to submit a payment A scenario for sending a payment.
How to submit an internal transfer A scenario for sending an internal transfer.
How to access ONE API The section gives instructions on how to obtain the credentials needed to use the ONE API, and connect our API sandbox.
Authentication This section explains how authentication works with the API, and how to get authentication data.
Veirfying callback signatures This section explains how to verify signatures included with payments' callbacks.
Accounts The section contains a description of API methods for working with accounts.
Payments The section contains a description of API methods for working with payments and transfers.
Transactions The section contains a description of API methods to get information about transactions.
ONE issues accounts in multiple currencies, and enable outbound payments in a large volume of currencies. Full details of supported currencies and payment corridors can be found here .
ONE issues two types of accounts:
GBP Domestic accounts are UK-issued accounts, in GBP only. GBP domestic accounts support payments via Faster Payments, CHAPS and transfers between GBP domestic accounts, either under the ownership of a single customer or other customers.
GBP domestic accounts have the following identifiers:
You can get the ONE Account ID
by:
International accounts are issued in GBP, USD and EUR. ONE international accounts support payments via SWIFT, SEPA (EUR in EEA only) and transfers between accounts, either under the ownership of a single customer or other customers.
ONE international accounts have the following identifiers:
You can get the ONE Account ID
by using the GetAccounts method.
SWIFT
: SWIFT payments exist within the SWIFT international payment network. The SWIFT payment network is used to send and receive international electronic payments in various currencies.
SEPA
: The SEPA is a pan-European network that allows you to send and receive payments in euros EUR between two cross-border bank accounts in the eurozone. The network is spread within the EEA area, Andorra, Monaco, San Marino, Vatican City State, Mayotte, Saint-Pierre-et Miquelon, Guernsey, Jersey and Isle of Man.
Faster Payments
: This can only be used for transactions within the UK for GBP payments. Faster Payments are subject to an upper limit of £250,000. Faster Payments can be completed 7 days a week, 365 days a year, with transactions being completed within 20 minutes.
CHAPS
: This can only be used for transactions within the UK for GBP payments. CHAPS have no upper or lower limit, but
transactions can only be completed between Monday-Friday, 8 am-17:00 GMT and not on bank holidays. Transactions
typically arrive within a day of being processed.
Transfers allow customers to make payments from one domestic account to another domestic account or one international account to another international account. In addition, transfers between international accounts can take advantage of our FX solution to change currencies at a competitive rate.
Transfers between domestic accounts are always like-for-like transactions.
When a payment is initiated, it exists in an initial status Unknown
, the payments service then carries out balance checks against the account (for the transaction value and the associated fee), and a payment transaction will be created, and a payment fee transaction is created.
When a payment is initiated, it exists in an initial status Unknown
, the payments service then carries out
balance checks against the account (for the transaction value and the associated fee), and a payment transaction will be
created, and a payment fee transaction is created.
At this phase, the transaction exists only with the ONE platform, but the platform can be interrogated, and the
transaction will be visible. Two transactions will exist representing the transaction and the fee, they will have
separate IDs, and we also see that the payment is in the Pending
status.
Then the payment goes through other statuses, where it will send the actual transactions to the bank, wait for their
processing, then send the fee, wait for the fee to be processed, and at the very end will see that the payment has
become in the completedPayment
(completedTransfer
for internal transfers) status.
All this time, the API user will pull the API and see that the payment is in some intermediate state, and so on until he sees that the payment is completed.
At the same time, the user can request details from the API for individual transactions in the payment, see how much money was sent and where, and the state of the payment.
IBAN
or accountID
for the required account.accountID
or IBAN
IBAN
or accountID
for the required source account (i.e.
which account will the funds be sent from).paymentID
for the submitted payment.COMPLETE
, REJECTED
).IBAN
or accountID
for the required source account (i.e.
which account will the funds be sent from) and also the accountID for the destination account.We provide a sandbox environment for you to work in and certify ahead of configuring your production API access. The process is as follows:
NOTE: This assumes the customer organisation has passed all the required KYC checks.
You can use the ONE API Sandbox to test your integration to the ONE API.
Access and authorisation mechanisms processes are standard across the sandbox and production environments.
All transactions in the sandbox environment are simulated.
ONE API Authentication requires both OAuth2 authentication and ONE custom authentication.
To obtain this, please:
The next step will be for the customer to configure access as described in the authentication section described Authentication.
After registering the administrator user record at ONE Platform the invitation email will be send to that email with first login link. Set the user password.
After registering the administrator user record at ONE Platform the invitation email will be send to that email with first login link. Set the user password.
To generate the JWT token use the POST /auth/token
API. Pass in the email and password of your administrator account.
Example:
POST /api/v1/auth/token HTTP/1.1
Host: integration-api.uk-sbx-1.credis.tech
Content-Type: application/json
Content-Length: 65
{
"email": "[email protected]",
"password": "Example"
}
Response will contain the JWT token valid for 1 hour. After token expiration just request the new one.
Encryption keys will be provided by the ONE support team to generate the custom auth payload. The encryption key is 32 bytes long and is encoded in Base64.
Generation of token consists of the following steps:
The API is being invoked on behalf of a specific customer user, therefore user identification is required.
There is a special case with master customers which are allowed to make requests on behalf of their subsidiary customers as configured in the partner auth key.
For such case, the additional subsidiary_customer_id
parameter should be provided in the payload.
Generate JSON as follows:
{
user_id = "c28bd88a-903d-4080-b1f1-0fd0ac0aec25",
email = "[email protected]",
created_date = "2022-05-13T13:45:22Z",
first_name = "Brian",
last_name = "Ferry"
}
Field | Required | Description |
---|---|---|
user_id | true | Customer user's unique ID. API is being used on behalf of given user. |
true | Customer user's email. | |
created_date | true | The date and time the customer user was created. Should be in ISO 8601 format. |
first_name | true | Customer user's first name. |
last_name | true | Customer user's last name. |
subsidiary_customer_id | false | The subsidiary customer's id to make api calls on behalf on. |
Encryption requires utilization of AES-GCM-SIV
cipher: Advanced Encryption Standard (AES) key to be used with the Galois/Counter Mode (GCM) mode of operation.
The encryption goes as follows:
Nonce
.Tag
.UTF-8
bytes. Allocate the same amount of bytes for Ciphertext
.Ciphertext
length, Nonce
length and Tag
length.Nonce
buffer.Ciphertext
buffer, starting at the end of Nonce
.Tag
buffer, starting at the end of Ciphertext
.Refer to example encryption helper class, written in C#:
public class CryptoHelpers
{
private const int TagLength = 16;
private const int NonceLength = 12;
public static byte[] EncryptAesGcm(byte[] key, byte[] plaintext)
{
var aes = new AesGcm(key);
var nonce = RandomNumberGenerator.GetBytes(NonceLength);
var ciphertextBuffer = new byte[plaintext.Length];
var tagBuffer = new byte[TagLength];
try
{
aes.Encrypt(nonce, plaintext, ciphertextBuffer, tagBuffer);
}
catch (CryptographicException ex)
{
throw new CryptoException("Failed to encrypt payload", ex);
}
var resultBuffer = new byte[NonceLength + ciphertextBuffer.Length + TagLength];
nonce.CopyTo(resultBuffer, 0);
ciphertextBuffer.CopyTo(resultBuffer, NonceLength);
tagBuffer.CopyTo(resultBuffer, NonceLength + ciphertextBuffer.Length);
return resultBuffer;
}
}
The resulting ciphertext from previous step is encoded in Base64 encoding.
To make requests put the JWT token into Authorization
header with Bearer
scheme, and custom auth token
into X-Partner-Authorization
header.
For example, request to get all accounts registered to the customer would look like:
GET /api/v1/accounts?sortCode=041377&accountNumber=00000002 HTTP/1.1
Host: integration-api.uk-sbx-1.credis.tech
Authorization: Bearer eyJraWQiOiJfEXAMPLEHDW57H9yVFUWqGPJXe0K01V05Js86nkLngw
X-Partner-Authorization: M90h61elLsEXAMPLEEUqhV4INebu67gw==
ONE will always sign the webhook events it sends to your endpoints. Signature is included in X-Signature
header.
This allows you to verify that the callback originates from ONE.
The secret key to verify signatures will be provided by ONE support team. It is a separate secret, hence not be confused with the key used for generation of authentication token.
ONE generates signatures using a hash-based message authentication code (HMAC
) with SHA-256
hash function.
The signature is in hexadecimal string format. For example for a signature like:
X-Signature: abcdef...
the deserialized signature would have this value:
byte[] signatureBytes = new byte[] { 0xab, 0xcd, 0xef, ... };