Создание платежа

Создаёт платёж и возвращает реквизиты, на которые плательщик должен совершить перевод.

POST /v1/payments

Параметры запроса

Параметр	Тип	Обязательный	Описание
ext_id	string	да	Идентификатор заказа в системе мерчанта, до 255 символов. Должен быть уникальным
amount	number	да	Сумма платежа в валюте, указанной в currency. Для RUB — от 100 до 300 000
currency	string	нет	Валюта суммы и страна приёма: RUB, KZT, AZN, TJS. По умолчанию — валюта терминала. См. Валюты и страны
method	string	нет	Метод оплаты. По умолчанию CARD
bank	string	нет	Код банка из справочника GET /v1/public/banks. Если не передан, банк определяется системой
country	string	нет	Страна получателя для методов CROSS_BORDER и CROSS_BORDER_CARD: TJ, KZ, UZ, KG
client_id	string	нет	Идентификатор плательщика в системе мерчанта
notify_url	string	нет	Адрес для отправки коллбэков
notification_token	string	нет	Токен, возвращаемый в заголовке X-Notification-Token при отправке коллбэка

Методы оплаты

Доступность методов по странам описана в разделе Методы оплаты.

Метод	Описание
CARD	Перевод на банковскую карту
PHONE	Перевод по номеру телефона внутри банка (вне СБП)
SBP	Перевод по номеру телефона через СБП. Только Россия
SBP_QR	Оплата по QR-коду СБП. Только Россия
SIM	Пополнение лицевого счёта абонента. Только Россия
CROSS_BORDER	Трансграничный перевод по реквизитам
CROSS_BORDER_CARD	Трансграничный перевод на карту

Передача параметра bank

Если вместе с методом CARD, SBP или SBP_QR передан параметр bank, платёж обрабатывается как внутрибанковский перевод: реквизиты подбираются строго в указанном банке. Если банк не важен, параметр передавать не следует — это увеличивает число доступных реквизитов. Для метода PHONE параметр bank задаёт банк получателя и режим платежа не меняет.

Приём в рублях

curl -X POST https://api.bopay.io/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-Identity: <API-key>" \
  -H "X-Signature: <Signature>" \
  -d '{
    "ext_id": "order_12345",
    "amount": 5000,
    "method": "SBP",
    "client_id": "user_789",
    "notify_url": "https://merchant.example/webhook",
    "notification_token": "<token>"
  }'

Приём в другой валюте

Добавляется один параметр — currency. Сумма указывается в этой же валюте, реквизиты подбираются в соответствующей стране.

curl -X POST https://api.bopay.io/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-Identity: <API-key>" \
  -H "X-Signature: <Signature>" \
  -d '{
    "ext_id": "order_12346",
    "amount": 50000,
    "currency": "KZT",
    "method": "PHONE"
  }'

Перечень валют и методов по странам — в разделе Валюты и страны.

Трансграничный приём

Страна задаётся параметром country. Сумма по умолчанию рублёвая:

curl -X POST https://api.bopay.io/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-Identity: <API-key>" \
  -H "X-Signature: <Signature>" \
  -d '{
    "ext_id": "order_12347",
    "amount": 10000,
    "method": "CROSS_BORDER_CARD",
    "country": "KZ"
  }'

Пример ответа

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ext_id": "order_12345",
  "amount": 5000,
  "currency": "RUB",
  "rate": 80.95,
  "payin_rate": 11,
  "terminal_id": "6f15ad5b-325f-44ca-8f36-233379dcaf4c",
  "terminal_name": "Sber Deep RUB",
  "status": "PENDING",
  "method": "SBP",
  "requisites": {
    "type": "sbp",
    "value": "+79001234567",
    "bank": "Сбербанк",
    "bank_code": "sberbank",
    "holder": "Иван И."
  },
  "payment_url": "https://pay.bopay.io/invoice?id=550e8400-e29b-41d4-a716-446655440000",
  "valid_until": "2026-01-30T12:30:00Z",
  "created_at": "2026-01-30T12:15:00Z"
}

Поля ответа

Поле	Тип	Описание
id	string	Идентификатор платежа (UUID)
ext_id	string	Идентификатор заказа мерчанта
amount	number	Сумма платежа
currency	string	Валюта суммы
rate	number	Курс валюты платежа к USDT, зафиксированный для этой сделки
payin_rate	number	Ставка мерчанта по приёму для этой сделки, %
terminal_id	string	Идентификатор терминала, через который проведён платёж
terminal_name	string	Название терминала
status	string	Статус платежа — см. Статусы
method	string	Метод оплаты
requisites.type	string	Тип реквизита: sbp, card, phone, qr
requisites.value	string	Номер телефона, номер карты или содержимое QR-кода
requisites.bank	string	Название банка получателя
requisites.bank_code	string	Код банка получателя
requisites.holder	string	Имя получателя
payment_url	string | null	Адрес платёжной страницы
valid_until	string	Время истечения платежа, ISO 8601
created_at	string	Время создания платежа, ISO 8601

Что делать с ответом

Реквизиты можно показать на своей странице либо перенаправить плательщика на payment_url. Платёж считается оплаченным только после статуса COMPLETED — о нём сообщит коллбэк.

Ответ по трансграничному платежу

Для методов CROSS_BORDER и CROSS_BORDER_CARD платёж принимается в стране из параметра country. Сумма по умолчанию рублёвая — конвертацию в местную валюту выполняет система; если передать currency страны приёма, сумма считается уже местной и не конвертируется. Объект requisites содержит сумму к оплате:

"requisites": {
  "type": "phone",
  "value": "+992901234567",
  "bank_name": "Vasl Bank",
  "country": "TJ",
  "currency": "TJS",
  "amount_local": 1237.39
}

Поле	Тип	Описание
requisites.country	string	Код страны получателя
requisites.currency	string	Валюта реквизитов
requisites.amount_local	number	Сумма к оплате в местной валюте

Сравнение обоих режимов — в разделе Валюты и страны.

Ошибки

Код	HTTP	Причина
PAY_002	400	Неверные параметры запроса, в том числе неподдерживаемая валюта
PAY_003	409	Заказ с указанным ext_id уже существует
PAY_004	503	Отсутствуют доступные реквизиты
PAY_005	429	Превышено число последовательных платежей с одинаковой суммой

Полный перечень приведён в разделе Ошибки.