Оплата QR-кодов

QR‑платёж позволяет покупателям быстро оплачивать товары и услуги, сканируя код через банковское приложение или любое другое приложение, поддерживающее QR‑оплату. Оплата QR кодов производится по аналогичному с выплатами механизму двухэтапного подтверждения платежа. На первом этапе происходит распознавание данных QR кода и расчет курса конвертации. На втором этапе происходит оплата.

Шаг 1. Распознавание QR‑кода и расчёт стоимости

На этом шаге ваш сервер передаёт строку, содержащую данные QR‑кода, в API. Система анализирует информацию, вычисляет сумму в локальной валюте и рассчитывает эквивалент в валюте расчета.

Пример QR-кода:

API Payler One (modern)

Запрос:

curl -X POST https://api.payler.one/v2/qr \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"tlv":"<СТРОКА_ИЗ_QR_КОДА>"}'

Описание полей:

access_token: string (required) - Authorization: Bearer
tlv: string (required) - Расшифрованная строка из QR-кода

Разбор ответа:

Status 200: In response, information about the QR code itself is sent, along with the request ID and a cost estimate.

{
    "_id": "6f163897-b94e-4e95-8c39-0dafa689fc71",
    "status": "calculated",
    "amountFrom": 309.52,
    "amountTo": 98000,
    "currencyFrom": {
        "_id": "6e65cf3c-c39d-4c5d-9fb0-159a1c054f2d",
        "type": "FIAT",
        "code": "RUB",
        "symbol": "₽",
        "label": "рубль",
        "decimal": 2,
        "countryName": "Russia",
        "countryCode": "RU"
    },
    "currencyTo": {
        "_id": "db8ca38b-52f0-4b7b-875f-8149d1616418",
        "type": "FIAT",
        "code": "VND",
        "symbol": "₫",
        "label": "₫",
        "decimal": 0,
        "countryName": "Vietnam",
        "countryCode": "VN"
    },
    "rate": 316.619281468,
    "reverseRate": 0.0031583673,
    "isCustomAmount": false,
    "merchant": {
        "country": "VN",
        "name": "QR4NQN9GTT McDonalds"
    },
    "metadata": {},
    "createdAt": "2026-02-27T09:52:53.945Z",
    "expiredAt": "2026-02-27T09:57:53.945Z"
}

Описание полей:

_id (uuid): Уникальный ID запроса, используется в следующем шаге оплаты;
status (string): Текущий статус платежа — может принимать значения paid, completed или canceled;

Note

Paid — оплата прошла успешно, терминал принял средства. Нефинальный статус, может измениться в течение 10 минут.
Completed — оплата прошла успешно (финальный статус).
Canceled — оплата не прошла (финальный статус).

amountFrom (number): Сумма списания (в исходной валюте);
amountTo (number): Сумма зачисления (в целевой валюте);
currencyFrom (object) : Данные исходной валюты;
currencyTo (object) : Данные целевой валюты;
_id (uuid): Уникальный ID валюты списания;
type (string): Тип валюты;
code (string): Код валюты;
symbol (string): Символ валюты;
label (string): Название или краткая метка валюты;
decimal (number): Количество знаков после запятой;
countryName (string): Название страны;
countryCode (string): Код страны;
rate (number): Курс обмена;
reverseRate (number): Обратный курс обмена;
isCustomAmount (bool) : Флаг, указывающий, была ли сумма введена пользователем вручную (false, если расчет произведен автоматически);
merchant (object) : Данные продавца;
country (string): Код страны регистрации или нахождения продавца;
name (string): Название продавца;
metadata (object) : Дополнительные метаданные;
createdAt (string): Дата и время создания расчета (в формате ISO 8601);
expiredAt (string): Дата и время истечения срока действия данного расчета/курса

Status 400: Authentication failed. Access token is invalid.

{
"error": "ERROR_ACCESS_TOKEN_INVALID",  
"message": "Access token is invalid.",  
"statusCode": 400  
}

error: string (required)
message: string (required)
statusCode: number

Status 401: Authentication failed. Access token has expired.

{
"error": "ERROR_TOKEN_EXPIRED",  
"message": "Access token has expired.",  
"statusCode": 401  
}

Status 403: QR code format is not supported right now.

{
"error": "ERROR_QR_CODE_NOT_SUPPORTED",  
"message": "This QR code not supported.",  
"statusCode": 403  
}

error: string (required)
message: string (required)
statusCode: number

Status 404: QR code expired.

{
"error": "ERROR_QR_CODE_EXPIRED",  
"message": "This QR code is expired.",  
"statusCode": 404  
}

error: string (required)
message: string (required)
statusCode: number

Status 405: No route found for this QR code.

{
"error": "ERROR_QR_NO_ROUTE_FOUND",  
"message": "Routing for this currency not set.",  
"statusCode": 405  
}

error: string (required)
message: string (required)
statusCode: number

Status 500: Project tariff not configured, pls contact with our support.

{
  "error": "TARIFF_NO_FOUND",  
  "message": "Project tariff not configured, pls contact with our support.",  
  "statusCode": 500  
}

error: string (required)
message: string (required)
statusCode: number

Status 501: Requested quote not found, pls contact with our support.

{
  "error": "QUOTE_NOT_FOUND",  
  "message": "Requested quote not found, pls contact with our support",  
  "statusCode": 501  
}

error: string (required)
message: string (required)
statusCode: number

Шаг 2. Финализация платежа

После подтверждения суммы клиентом необходимо отправить запрос на завершение сделки.

Запрос:

curl -X POST https://api.payler.one/v2/qr/{id}/pay \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \

access_token: string (required) - Authorization: Bearer
{id}: uuid (required) - _id из ответа на запрос /qr

Разбор ответа:

Status 200: Successfully created a new payout deal.

Status 400: Invalid request, typically due to a missing or malformed parameter.

{
"error": "ERROR_ACCESS_TOKEN_INVALID",  
"message": "Access token is invalid.",  
"statusCode": 400  
}

error: string (required)
message: string (required)
statusCode: number

Status 401: Authentication failed. This may happen due to the following reasons:
Authentication is required but not provided.

The access token has expired.

{
"error": "ERROR_TOKEN_EXPIRED",  
"message": "Access token has expired.",  
"statusCode": 401  
}

error: string (required)
message: string (required)
statusCode: number

Status 403: QR code format not supported right now.

{ 
"error": "ERROR_QR_CODE_NOT_SUPPORTED",  
"message": "This QR code not supported.",  
"statusCode": 403  
}

error: string (required)
message: string (required)
statusCode: number

Status 404: QR code expired.

{ 
"error": "QR_CODE_EXPIRED",  
"message": "QR code expired.",  
"statusCode": 404  
}

error: string (required)
message: string (required)
statusCode: number

Status 405: No route found for this QR code.

{ 
"error": "ERROR_QR_NO_ROUTE_FOUND",  
"message": "Routing for this currency not set.",  
"statusCode": 405  
}

error: string (required)
message: string (required)
statusCode: number

Status 409: Conflict occurred because a deal with the same invoice ID already exists.

{ 
"error": "TRANSACTION_ALREADY_EXISTS",  
"message": "Transaction with same invoiceId already exists.",  
"statusCode": 409  
}

error: string (required)
message: string (required)
statusCode: number

Status 500: Project tariff not configured, pls contact with our support.

{
  "error": "TARIFF_NO_FOUND",  
  "message": "Project tariff not configured, pls contact with our support.",  
  "statusCode": 500  
}

error: string (required)
message: string (required)
statusCode: number

Status 501: Requested quote not found, pls contact with our support.

{
  "error": "QUOTE_NOT_FOUND",  
  "message": "Requested quote not found, pls contact with our support.",  
  "statusCode": 501  
}

error: string (required)
message: string (required)
statusCode: number

Запрос курса валюты

Запрос:

curl -X GET https://api.payler.one/v2/qr/rate/?currencyCodes=TRY \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \

access_token: string (required) - Authorization: Bearer
currencyCodes: string (required) - ISO-код валюты из ответа на запрос /qr

Разбор ответа:

Status 200:

{
  "rates": {
    "code": "TRY",  
    "rate": 0.4926108374  
  }
}

Описание полей:

code (string): ISO-код валюты;
rate (number): Полный курс валюты

Note

В случае, если курс не удалось посчитать или запрашиваемый код валюты не существует, в качестве ответа придёт пустое поле без дополнительных сообщений об ошибке.

Проверка статуса платежа

Запрос:

curl -X GET https://api.payler.one/v2/qr/{id} \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \

access_token: string (required) - Authorization: Bearer
{id}: uuid (required) - _id из ответа на запрос /qr

Разбор ответа:

Status 200:

{
    "_id": "6c57b453-f360-41c3-9a99-be05c0136104",  
    "status": "completed",  
    "amountFrom": 309.31,  
    "amountTo": 98000,  
    "currencyFrom": {
        "_id": "6e65cf3c-c39d-4c5d-9fb0-159a1c054f2d",  
        "type": "FIAT",  
        "code": "RUB",  
        "symbol": "₽",  
        "label": "рубль",  
        "decimal": 2,  
        "countryName": "Russia",  
        "countryCode": "RU"  
    },
    "currencyTo": {
        "_id": "db8ca38b-52f0-4b7b-875f-8149d1616418",  
        "type": "FIAT",  
        "code": "VND",  
        "symbol": "₫",  
        "label": "₫",  
        "decimal": 0,  
        "countryName": "Vietnam",  
        "countryCode": "VN"  
    },
    "rate": 316.8342439623,  
    "reverseRate": 0.0031562244,  
    "isCustomAmount": false,  
    "merchant": {
        "country": "VN",  
        "name": "QR4NQN9GTT McDonalds"  
    },
    "metadata": {},
    "createdAt": "2026-02-27T11:46:06.844Z",  
    "expiredAt": "2026-02-27T11:51:06.844Z",  
    "completedAt": "2026-02-27T11:46:39.539Z"  
}

Описание полей:

completedAt (string): Дата и время выполнения расчета (в формате ISO 8601);

Status 400: Invalid request, typically due to a missing or malformed parameter.

{
"error": "ERROR_ACCESS_TOKEN_INVALID",  
"message": "Access token is invalid.",  
"statusCode": 400  
}

error: string (required)
message: string (required)
statusCode: number

Status 401: Authentication failed. This may happen due to the following reasons:
Authentication is required but not provided.

The access token has expired.

{
"error": "ERROR_TOKEN_EXPIRED",  
"message": "Access token has expired.",  
"statusCode": 401  
}

error: string (required)
message: string (required)
statusCode: number

Status 500: Transaction with specified ID not found.

{
"error": "TRANSACTION_NOT_FOUND",  
"message": "Transaction with specified ID not found.",  
"statusCode": 500  
}

error: string (required)
message: string (required)
statusCode: number

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search