Mandarin

# BaaS

# ESP testing

To test the creation of an ESP, a separate sanbox service is used, which, depending on the transferred full name, creates an ESP for successful and unsuccessful operations.

# Connecting to the test environment

Before starting the integration, please contact Support Service (opens new window) to obtain:

  • client_idAndclient_secretOAuth applications;
  • access to Sandbox for the virtual accounts API;
  • (optional) settings webhook URL for notifications about the status of wallets.

This data is used to obtainaccess_tokenand making requests to the API.

# Virtual Account API Environments

Environment Base URL
Sandbox https://sandbox-payment-tokens.mandarin.io
Production https://payment-tokens.mandarin.io

# OAuth scopes

To work with virtual accounts, request scopes separated by a space, for example:

payment-tokens:tokens.write payment-tokens:tokens.read payment-tokens:otp.write
Scope Destination
payment-tokens:tokens.write Creation of ESP
payment-tokens:tokens.read Checking ESP status
payment-tokens:otp.write Sending and confirming OTP

# Authentication

Requests to the virtual account API in the test environment are authenticated using the OAuth 2.0 (Bearer) protocol. For more details, see the Request Authentication section.

# Test names for creating ESP

In Sandbox, the result of creating a wallet depends on the given full name:

# Successful wallet creation

Field Meaning
first_name Success
last_name Successful
middle_name Uspekhovich

# Error creating wallet

Field Meaning
first_name Failure
last_name Unsuccessful
middle_name Unuspekhovich

# Creating a virtual account (ESP)

Request

curl --request POST \
  --url https://sandbox-payment-tokens.mandarin.io/api/v1/tokens/generate \
--header 'Mid: {{mid}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
    "first_name": "Иван",
    "last_name": "Иванов",
    "middle_name": "Иванович",
    "birth_date": "1990-12-22",
    "citizenship": "RU",
    "registration_address": "г. Москва, ул. Петровка, д.2, кв.1",
    "living_address": "г. Москва, ул. Петровка, д.2, кв.1",
    "document": {
        "document_type": "Passport",
        "serial": "1234",
        "number": "123456",
        "issue_date": "2002-04-24T15:23:14.969Z",
        "birth_place": "г. Москва",
        "issuer": "ОВД района Фили Давыдково",
        "issue_code": "404-004",
        "expiration_date": null
    },
    "inn": "1234567890",
    "snils": "140-120-150 35",
    "phones": [
        {
            "phone": "79004001234",
            "type": "Personal"
        }
    ],
    "email": "ivanoff@mail.ru",
    "phone_check": true,
    "terms_agreement": true,
    "is_public_official_person": false,
    "presence_of_beneficiary": false,
    "beneficiary_information": false,
    "exist_fatf_government_bills": false,
    "affiliation_with_foreign_taxpayers": false
}'

Response in case of a successful request to create a virtual account (ESP) (200 OK)

{
    "id": "06dca2f1-4e1c-44e7-8848-3e9e3adba875",
    "status": "Processing",
    "created_at": "2025-11-21T10:33:27.021823Z",
    "processed_at": null,
    "finished_at": null
}

# Testing card2wallet2account

The card2wallet2account scenario (replenishing ESP from a card + partial routing to sub-merchants) is being tested in Sandbox. The technical description of the operation is in the [BaaS] section (./api_baas.md#replenishment-ESP-from-card-and-routing-sub-merchants-card2wallet2account).

# Checklist before the first test payment

  • ✓ Sandbox receivedclient_id,client_secret, M.I.D.
  • ✓ The OAuth token is requested with the necessary scopes:secure:transactions.write payment-tokens:tokens.read(to create an ESP additionally:payment-tokens:tokens.write payment-tokens:otp.write)
  • ✓ A test ESP has been created and activated (status = Success) - see Test full name
  • ✓ At least one createdaccountIdsub-merchant
  • ✓ The card2wallet2account script is connected to the Mandarin manager
  • ✓ Configured callback URL (accessible from outside or through a tunnel)
  • ✓orderIdunique for each request

# Test scenarios

# Script Waiting
1 Full routing:price = 100, routing = 100 Success, all funds distributed
2 Partial routing:price = 100, routing = 50 Success, 50 ₽ per sub-merchant, 50 ₽ per wallet
3 Excess:price = 100, routing = 150 Error 400
4 ESP is not activated (status != Success) Error creating transaction
5 IncorrectaccountId Error creating transaction
6 RepeatedorderId Error or idempotent response (depending on settings)

# Checking your wallet balance

After successful payment with partial routing, check your balance:

curl --request GET \
  --url https://sandbox-payment-tokens.mandarin.io/api/v1/tokens/{{payment_token_id}}/wallet/balance \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Mid: {{mid}}'

If errors occur, see BaaS (ESP) in the error code directory.

← Operation types →