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:

1. GBP domestic accounts,
2. International 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:

• international bank account number (IBAN),
• AccountNumber and SortCode,
• Account ID is a GUID uniquely identifying a given account in the ONE network.

You can get the ONE Account ID by:

• using Create Domestic account method after the account creation;
• using the GetAccounts method.

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:

• International bank account number (IBAN),
• Account ID is a GUID uniquely identifying a given account in the ONE network.

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.

1. Use GetAccounts call to retrieve the account details for the connected customer.
2. From the return list select the IBAN or accountID for the required account.
3. Submit GetTransactions using the required accountID or IBAN
   • the return set can be limited by a combination of the query parameters,
   • pagination for the response can also be configured.

1. Use GetAccounts call to retrieve the account details for the connected customer.
2. From the return list select the IBAN or accountID for the required source account (i.e. which account will the funds be sent from).
3. Gather the required information for the required payment type (SWIFT, SEPA) as per the specification.
4. For a SEPA payment submit a createSEPApayment call using the source account and defined information.
5. This will return a paymentID for the submitted payment.
6. Use GetPaymentById call to check the status of the payment until it reaches a final status (COMPLETE, REJECTED).

1. Use GetAccounts call to retrieve the account details for the connected customer.
2. From the return list select the 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.
3. Gather the required information for the required transfer as per the specification.
4. Submit the transfer using the CreateInternalTransfer call.

We provide a sandbox environment for you to work in and certify ahead of configuring your production API access. The process is as follows:

1. Request access to the ONE API Sandbox environment.
2. Configure access to the sandbox environment.
3. Customer build and test cycle to integrate to the APIs.
4. Pass certification by ONE (validate calls are as per specification and usage is as expected).
5. You get access provided to production APIs.

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:

• send an email with a request to [email protected];
• the email should contain:
  • name of your organisation,
  • email that will be the identifier of the organisation when accessing the API;
• you will receive the details necessary to connect the API to the specified email;
• at the same time, we will create an account for this email in the ONE authentication system, and you will receive an email with links and prompts to set a password for this account.

The next step will be for the customer to configure access as described in the authentication section described Authentication.

The crypto payment gateway facilitates the acceptance of cryptocurrency payments. It also involves submitting transactions, querying information, or accessing various blockchain functionalities.

The Crypto Gateway service is designed to provide a seamless and secure gateway for handling cryptocurrency transactions for your merchant. This service facilitates the integration and management of cryptocurrency payments, ensuring a smooth user and merchant experience.

To initiate your integration successfully, follow these steps:

1. Ensure that your Organisation has been onboarded by the ONE.io team.
2. Ensure that your Organisation has API access enabled.
3. Obtain access to the ONE API Sandbox environment for testing and developing your integration in a controlled environment before going live.
4. Generate a JWT (JSON Web Token) to authenticate your API requests securely. This token serves as a means to verify your application's identity when interacting with the ONE API.
5. Implement the necessary mechanisms to verify callback signatures. This step ensures the integrity and authenticity of callbacks received from ONE.io.
6. Confirm that the Crypto Gateway and Crypto Trading services are enabled for your Organisation to leverage its features.

By completing these steps, you'll establish a strong foundation for a successful integration with ONE.io. Refer to the detailed documentation for each step to ensure a smooth setup process. Our support team is ready to assist you with any issues or questions.

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:

1. JSON payload generation
2. Payload encryption
3. Encoding binary payload to Base64

JSON payload generation

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

Payload encryption

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:

• Generate the 12 bytes cryptographic Nonce.
• Allocate 16 bytes for generated Tag.
• Encode the JSON payload as UTF-8 bytes. Allocate the same amount of bytes for Ciphertext.
• Perform the encryption.
• Allocate the resulting buffer, length must be the sum of Ciphertext length, Nonce length and Tag length.
• Copy to allocated buffer, in this specific order:
  • 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;
    }
}

Ciphertext encoding

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, ... };

Extract the callback's payload bytes.

Example code in C# can be used to calculate the signature for given payload and secret.

public byte[] CalculateSignature(byte[] payload, byte[] secret)
{
    using var hmacSha = new HMACSHA256(secret);
    var hashBytes = hmacSha.ComputeHash(payload);
    return hashBytes;
}

Compare the signature received in callback in X-Signature header with expected signature.

Actions with accounts

Authentication actions

Crypto Payments Gateway operations

Exchange rates

Current organisation info

Payments initiation

Working with transactions