Guides
Guides

Getting started

Suggest Edits

This tutorial helps you get started with Yordex and has the following sections:

API overview

This tutorial is divided into three categories:

  • Account setup APIs: needed to create accounts. You don't need to use these APIs if we set up the accounts for you.
  • App APIs: needed to build your own mobile and web apps for end users. You don't need to use these APIs if your end users use the Yordex mobile app or web app. Our apps can be white labeled.
  • Admin APIs: needed to administer the service and get reports. You don't need to use these APIs if you use our Admin portal instead.
  • References: background information about our APIs

There is no difference between the APIs in the different sections. We just organised it like this for readability.

🚧

Not all fields are explained in the tutorials

Our APIs contain a number of fields that our mobile app and web app use but that you will probably not need.

You can ignore all fields returned by our API but not explained in these tutorials. If there are some fields you would like to use, please contact us

Basic terms

The following terms will be used throughout this documentation:

  • Payments: are card payments, account-to-account bank transfers, cross-border payments or transfers between Yordex accounts. They contain only the information provided by the bank provider and not any information provided by you or Yordex (which is all stored in orders).
  • Orders: represent invoices and receipts. They are used to schedule payouts, reconcile payments with invoices and receipts, and when using the Yordex app, collect additional information about payments such as tax codes, cost allocations, receipts etc.
  • Traders : are businesses, either your customers (so the account owners) or suppliers. Every order has a buyer and a seller both of whom are traders.
  • Users: are individuals linked to traders. They are usually the customer's employees but they can also be their beneficiaries

📘

You cannot create a payment directly

It is not possible to create a payment by API. To schedule a payment, you have to create an order

Base URLs

In the this documentation we use {baseUrl} in all code examples, see the example below.

Our base URLs are:

Authentication

You can authenticate using our API keys.

To create an API key you can use the following process:

Firstly, retrieve a session token for your admin user:

curl {baseURL}/sessions
-H "Content-Type: application/json"
-X POST
-d'{
    "username":"[email protected]",      
    "password":"Password123"
}'

The response will look like this:

{
    "token": "Session Auth Token", // Required for next step
    "tokenType": "BASIC_USER_LOGIN_TOKEN",
    "userType": "TRADER_USER",
    "permissions": [
        "LOGIN_WITH_OTP",
        "PERM_UPDATE_USER_MOBILE_NUMBER_FOR_OTP"
    ],
    "username": "[email protected]",
    "userId": "[email protected]",
    "ssoToken": false,
    "mobileNumber": "Mobile Number",
    "mobileNumberCountryCode": "44",
    "otpInfo": {
        "otpStatus": "SMS_SENT"
    },
    "roles": [
        "ROLE_TRADER_ADMIN"
    ]
}

Use the Session Auth Token and the OTP sent to the requested user to authenticate the following API:

Note: If the user's mobile number is not configured the SMS may not be delivered. The user can be updated with a PUT request.

curl {baseURL}/sessions/otp
-H "Authorization:Session Auth Token"
-H "Content-Type: application/json"
-X POST
-d'{
    "otp":"OTP code" // Received via SMS
}'

The response will look like this:

{
    "token": "Admin user session token"
}

Finally, you can request to create an API token using the following request

curl {baseURL}/api-keys/trader-tokens 
-H "Authorization: Admin user session token"  
-H "Content-type: application/json"  
-X POST
-d'{
            "name": "apiKeyName"
}'

The response will look like this:

Make note of your API key, this cannot be retrieved again

{
    "id": "3968c250-76b1-4058-98fb-b0123338ed40",
    "creationDateTime": "2023-05-30 13:52:22",
    "token": "your-api-key", // API key
    "name": "apiKeyName",
    "enabled": true
}

The API key is sent in the "Authorization" field of the HTTP header. The example below shows what that looks like when creating a card:

curl {baseURL}/cards  
-H "Authorization:your-api-key"  
-H "Content-type: application/json"  
-X POST  
-d '{ 
  "virtual": true,
  "userId": "[email protected]",
  "currency": "USD",
  "accountId": "id"
}'

Our mobile and web apps use session tokens which are created using the sessions API. This relies on 2-factor authentication and is therefore not practical for API calls.

Pagination

Most APIs used for getting a list of objects support pagination (GET on /orders, GET on /users, GET on /reports etc.)

The paginate results, you can use the following filters:

  • size specifies the number of results to be returned. The default is 10
  • sort defines the sort order of the returned orders, e.g. "?sort=creationDate,desc" sorts orders by creation date in descending order. ''asc" is used for ascending order.
  • page is the page number of the results to be returned, e.g. "?page=0" is the first page of the results

Test environment

Our test environment is an exact copy of our live environment with the only difference that it is not connected to payments systems so no real payments will be made.

You can login to our test environment by going to https://new-app.test.yordex.com. Please contact us to get your login details.

Updated over 1 year ago

What’s Next