ONE API (v1.0)

Download OpenAPI specification:Download

ONE Backend Team: [email protected]

Introduction

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.

Contents

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.

Supported destinations and currencies

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 .

Work with accounts

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:

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.

Payment types and transfers

International payment options

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.

GBP domestic payment options

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.

Outbound Payments & Transfers Options

Transfers

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.

Technical implementation of payments

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.

payment_statuses

How to query Transaction history

How to query Transaction history

  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.

How to submit a payment

How to submit a 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 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).

How to submit an internal transfer

How to submit an internal transfer

  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.

How to access ONE API

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.

How to access the ONE API Sandbox

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.

Binance Pay specification

What is the Binance Pay

Binance Pay is a contactless, borderless, secure cryptocurrency payment technology designed by Binance. Binance Pay allows customers to pay and get paid in crypto worldwide.

Overview

This guide explains how merchants can easily integrate Binance Pay QR Codes into their systems using ONE.io. The process involves generating QR Codes for products and services, displaying them in the merchant system, and letting users pay with Binance.

Within this service, orders can be created in either cryptocurrency or fiat currency. For fiat orders, an automatic conversion to USDT will occur at the market rate. Additionally, merchants retain the flexibility to indicate their preferred payment currency and the order expiration time for users.

Getting Started

To initiate your integration successfully, follow these steps:

  1. Ensure that the ONE.io team has onboarded your merchant.
  2. Ensure that your merchant 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 Binance Pay service is enabled for your merchant 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.

Merchant Acquiring - Payment by QR code

ONE.io works with Binance to create QR Codes for different products. Merchants receive these unique QR Codes from ONE.io, making it easy for their users to pay in crypto.

The following simple steps allow users to pay using the Binance app:

  • Scan with the Binance Pay app the displayed QR Code.
  • Confirm the payment by entering a passcode or clicking "confirm" in the Binance app.

Once a user successfully pays, Binance notifies ONE.io about the payment status in real-time.

ONE.io then informs the merchant about the payment status, keeping them informed and enhancing transparency.

binance_pay_merchant_acquiring

Crypto Payment Gateway specification

What is Crypto Payment Gateway

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

Overview

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.

Getting Started

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.

Authentication

JWT token generation

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.

Bearer

Enter JWT Bearer token only

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Partner

The partner encrypted token

Security Scheme Type API Key
Header parameter name: X-Partner-Authorization