Валюты и страны

Приём платежей во всех странах выполняется одним эндпоинтом POST /v1/payments. Страна определяется параметром currency, который задаёт валюту суммы amount и, соответственно, страну подбора реквизитов.

Если параметр не передан, используется валюта терминала, указанная в его настройках.

Поддерживаемые направления

Страна	currency	Методы	Как оплачивает плательщик	Коды банков
Россия	RUB	CARD, SBP, SBP_QR, SIM	Перевод на карту, по номеру телефона через СБП, по QR-коду СБП, пополнение счёта телефона	sberbank, tinkoff, alfabank, vtb, …
Казахстан	KZT	CARD, PHONE, CROSS_BORDER, CROSS_BORDER_CARD	Перевод на карту или по номеру телефона внутри банка; также доступен трансграничный приём. СБП в Казахстане не применяется	kaspi, halyk_bank, jusan_bank, forte
Азербайджан	AZN	CARD, PHONE	Перевод на карту или по номеру телефона	—
Таджикистан	TJS	CARD, CROSS_BORDER, CROSS_BORDER_CARD, CROSS_BORDER_SIM	Перевод на карту или по номеру телефона; также пополнение счёта у оператора связи	eskhata, alif_bank, arvand, …

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

Актуальный перечень банков возвращает GET /v1/public/banks.

Пример: Казахстан, 50 000 тенге

Сумма передаётся в тенге, реквизит подбирается среди казахстанских банков:

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": 50000,
    "currency": "KZT",
    "method": "PHONE"
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 50000,
  "currency": "KZT",
  "rate": 463.19,
  "status": "PENDING",
  "requisites": {
    "type": "phone",
    "value": "+77012345678",
    "bank": "Kaspi Bank",
    "bank_code": "kaspi",
    "holder": "Ivan I."
  },
  "payment_url": "https://pay.bopay.io/invoice?id=550e8400-e29b-41d4-a716-446655440000"
}

Курс

rate — курс валюты заявки к USDT, зафиксированный в момент создания платежа; по этой сделке он больше не пересматривается. Источник курса определяется настройками терминала, отдельно для каждой валюты.

Ошибки валюты

Причина	Ответ
Валюта не поддерживается	400, PAY_002
Отсутствуют доступные реквизиты в этой валюте	503, PAY_004

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

Методы CROSS_BORDER и CROSS_BORDER_CARD — приём в стране, указанной в параметре country. Сумму можно передавать в двух валютах, поведение задаётся тем же необязательным currency.

Сумма в рублях (по умолчанию)

currency не передаётся, конвертацию выполняет система:

{ "ext_id": "order_1", "amount": 10000, "method": "CROSS_BORDER_CARD", "country": "KZ" }

Плательщик вносит сумму в местной валюте, в вашем учёте заказ остаётся на 10 000 ₽:

"requisites": {
  "type": "card",
  "value": "4400430212345678",
  "bank_name": "Kaspi Bank",
  "country": "KZ",
  "currency": "KZT",
  "amount_local": 54500.00
}

Сумма в местной валюте

Передайте currency страны приёма:

{ "ext_id": "order_2", "amount": 50000, "currency": "KZT",
  "method": "CROSS_BORDER_CARD", "country": "KZ" }

Конвертация не выполняется: amount_local равен amount, а rate в ответе — курс тенге к USDT.

Сравнение режимов

	currency не передан	currency: "KZT"
Валюта amount	рубли	тенге
Конвертация	по курсу системы	не нужна
requisites.amount_local	пересчитанная сумма	равна amount
Заказ в вашем учёте	рублёвый	тенговый

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

Трансграничный SIM (пополнение счёта оператора)

Метод CROSS_BORDER_SIM — трансграничный приём, при котором плательщик пополняет лицевой счёт абонента у оператора связи страны приёма. Правила ровно те же, что у CROSS_BORDER и CROSS_BORDER_CARD: сумма по умолчанию рублёвая, конвертацию выполняет система, плательщик вносит местную валюту.

Оператор передаётся в параметре bank; если он не указан, реквизит подбирается среди всех операторов страны из параметра 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_77",
    "amount": 5000,
    "method": "CROSS_BORDER_SIM",
    "country": "TJ",
    "bank": "tcell"
  }'

{
  "id": "7c1f...",
  "amount": 5000,
  "currency": "RUB",
  "status": "PENDING",
  "requisites": {
    "type": "sim",
    "value": "+992900000001",
    "bank": "tcell",
    "bank_name": "Tcell",
    "country": "TJ",
    "currency": "TJS",
    "amount_local": 540.25
  },
  "payment_url": "https://pay.bopay.io/invoice?id=7c1f..."
}

Плательщик пополняет счёт +992900000001 на amount_local в местной валюте.

Сумма в местной валюте

Как и у остальных трансграничных методов, сумму можно передать сразу в валюте страны приёма — добавьте "currency": "TJS". Конвертация тогда не выполняется: amount_local равен amount, а заказ в вашем учёте ведётся в сомони.

Операторы

Коды операторов возвращает GET /v1/public/banks вместе с банками: для Таджикистана это tcell, babilon_mobile, megafon_tjs, beeline_tj, zet_mobile. Операторы заведены и для других направлений приёма — Узбекистана, Казахстана, Киргизии, Азербайджана, Армении и Грузии.

Отличия от метода SIM

	SIM	CROSS_BORDER_SIM
Страна	Россия	страна из country
Валюта суммы	рубли	рубли (или валюта страны приёма)
Что вносит плательщик	ту же сумму в рублях	сумму в местной валюте
requisites.type	sim	sim

Если реквизиты по методу отсутствуют, возвращается 503 с кодом PAY_004.