Getting started

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

• API overview
• Basic terms
• Base URLs
• Authentication
• Test environment

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.
• 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.
• 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.

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, bank transfers or internal account transfers and contain only the information provided by the bank provider.
• Orders: group one or multiple payments and store additional data about the payment. Orders are also used to trigger payments (see below)
• Traders : are businesses or persons, either your customers (so the payers), their employees, beneficiaries or suppliers (payees). Both the buyer and the seller of an order are traders.
• Users: are also employees or beneficiaries of your customers. See below for an explanation of the difference between users and traders

Orders vs Payments

Orders encapsulate payments:

• Orders contain more information than payments, for example a link to the supplier (trader), approvals, receipts, categorisations and, if provided, line item details
• Orders can group multiple payments. For example, subscriptions or orders with partial payments have more than one payment

📘

You cannot create a payment directly

To ensure all payments are made within your spend policy, it is not possible to call the payments API directly. Policies are defined at the card or order level so all payments are either triggered by cards or orders.

To pay out to someone you can either

• Give them a card and top up the card
• Create an order linked to a card and the order will top up the card
• Create an order that will trigger a bank transfer (same tutorial)

A more detailed description of the difference between orders and payments can be found here.

Users vs Traders

The table below describes the difference between users and Traders:

Suppliers are always Traders as a business does not need to control what their suppliers spend the money on.

Employees or beneficiaries can be both Users and Traders. For example, a business can give their employees a company card (User), but if an employee pays on their personal card the business can reimburse them on their personal bank account (Trader). For beneficiaries, a business can create a Yordex card in their name so the business can control what the user spends it on (User) or they can transfer the money to the beneficiary's own bank account (Trader).

Base URLs

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

Our base URLs are:

• Live environment: https://api.yordex.com/v1
• Test environment: https://api.test.yordex.com

Authentication

You can authenticate using our API keys. Please contact us to get your API key.

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

Test environment

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

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