# Трансграничный перевод

Плательщик в России платит **рублями из своего банка**, а реквизит — телефон или карта **в
другой стране**, например в Таджикистане или Узбекистане. Получатель получает местную валюту
(сомони, сумы), конвертацию делает платёжная сторона. Для вас это рублёвая заявка: сумма, курс,
ставка и зачисление в USDT считаются так же, как у [СБП](sbp.md) и [перевода на карту](card.md).

Страну получателя вы не выбираете: её выбирает платёжная сторона и присылает в ответе. Покажите
её плательщику, чтобы он знал, куда переводит.

<div class="pp-seq" data-lanes="Ваш сервер|API|Плательщик" markdown>

1. **Ваш сервер → API.** `POST /api/v1/payments` с `payment_method=cross_border_card` и `bank_code=Т-Банк` (банк плательщика)
2. **API.** Подбирает реквизиты для перевода из этого банка
3. **API ⇢ Ваш сервер.** `201`: `status=processing`, `requisite` — телефон или карта, `requisite_bank`, `cross_border_country`
4. **Ваш сервер → Плательщик.** Реквизит, получатель, банк и страна получателя, сумма в рублях и срок
5. **Плательщик.** Переводит рубли из приложения своего банка
6. **API → Ваш сервер.** Callback: `completed` или `canceled`

</div>

## Методы { #methods }

| `payment_method` | Реквизит | Как платит клиент |
| --- | --- | --- |
| `cross_border_sbp` | номер телефона | трансграничным переводом по номеру телефона |
| `cross_border_card` | номер карты | переводом на карту в другой стране (c2c) |

Метод должен быть в договоре вашего проекта, как `sbp` и `card_transfer`: проверьте
[лимиты договора](sbp.md#contract-limits) — там будут записи с этими методами.

## Банк плательщика и ставка { #payer-bank }

`bank_code` — банк, **из которого платит клиент**, как у `sbp` и `card_transfer`: название из
[справочника](banks.md) страны `geo_code` (`Т-Банк`, `Сбер`, `Альфа`). Ставка и выбор платёжной
стороны зависят от метода и банка: например, `cross_border_card` + Т-Банк и
`cross_border_sbp` + Сбер — разные записи договора со своими ставками. Без `bank_code` — любой
банк по записи «любой банк».

Страна получателя на ставку не влияет: в одну запись договора входят переводы и в Таджикистан,
и в Узбекистан.

## Создать заявку { #create }

`POST /api/v1/payments` — [подписанный](signing.md) запрос, как у других методов.

**Из конкретного банка** — с `bank_code` банка плательщика:

```json
{"merchant_payment_id": "order-47", "amount": 25000, "currency": "RUB", "geo_code": "RU",
 "payment_method": "cross_border_card", "bank_code": "Т-Банк"}
```

**Из любого банка** — без `bank_code`:

```json
{"merchant_payment_id": "order-46", "amount": 10000, "currency": "RUB", "geo_code": "RU",
 "payment_method": "cross_border_sbp"}
```

### Поля { #fields }

| Поле | Обяз. | Правила |
| --- | --- | --- |
| `payment_method` | да | `cross_border_sbp` или `cross_border_card` |
| `geo_code` | нет | Страна **плательщика**, по умолчанию `RU` |
| `currency` | нет | Валюта **плательщика**, по умолчанию `RUB`: сумма заявки в ней |
| `bank_code` | нет | Банк **плательщика** — название из [справочника](banks.md) страны `geo_code`, например `Т-Банк`. Без него — любой банк |
| `amount`, `merchant_payment_id`, `callback_url`, `client_id`, `client_username`, `client_ip` | — | Как у [СБП](sbp.md#request-fields) |

Страны получателя в запросе нет: поле `cross_border_country` в запросе — ошибка `400`.

## Ответ и callback { #response }

Ответ и callback — те же, что у [СБП](sbp.md#response), плюс поле `cross_border_country`:

```json
{
  "id": "3f1c2b9e-6a8d-4c4b-9a71-2c7f5d1e0a42",
  "merchant_payment_id": "order-47",
  "status": "processing",
  "amount": 25000,
  "currency": "RUB",
  "geo_code": "RU",
  "payment_method": "cross_border_card",
  "bank_code": "Т-Банк",
  "cross_border_country": "TJ",
  "requisite": "4444888815426816",
  "requisite_bank": "Банк Эсхата",
  "holder_name": "Фаридун Р.",
  "merchant_information": {"course": 82.50, "rate": 9.00, "amount_usdt": "303.0303",
    "amount_rate": "22750.0000", "amount_usdt_rate": "275.7575"}
}
```

- `requisite` — телефон у `cross_border_sbp`, номер карты у `cross_border_card`. Покажите его
  плательщику вместе с `holder_name`, `requisite_bank` и страной: плательщик выбирает в
  приложении страну и банк получателя.
- `cross_border_country` — страна получателя (`TJ` — Таджикистан, `UZ` — Узбекистан), её
  выбрала платёжная сторона. Поля нет, пока реквизит не выдан или если страна неизвестна.
- `bank_code` — банк плательщика из запроса; `requisite_bank` — банк получателя, в котором выдан
  реквизит.
- У заявок других методов `cross_border_country` нет.

## Расчёт { #settlement }

Заявка рублёвая: `merchant_information` — тот же [расчёт](sbp.md#merchant-information) по курсу
USDT/RUB и ставке вашего договора для метода и банка трансграна. Валюта страны получателя в
расчёт не входит.

## Ошибки { #errors }

| HTTP | `error` | Когда |
| --- | --- | --- |
| 400 | `bad_request` | В запросе есть `cross_border_country` или другое неизвестное поле |
| 422 | `cross_border_invalid` | `bank_code` — банк другой страны, а не банк плательщика из `geo_code` (например банк Таджикистана) |
| 422 | `bank_not_found` | `bank_code` нет в справочнике |
| 422 | `payment_not_covered` | Метода и банка трансграна нет в договоре или сумма вне диапазона |
| 422 | `payment_not_routable` | Сейчас принять перевод из этого банка нельзя |

!!! warning "Банк другой страны — ошибка"
    `bank_code` у любого метода — банк плательщика. Банк Таджикистана или Узбекистана в
    `bank_code` отклоняется (`422 cross_border_invalid`): банк получателя выбирает платёжная
    сторона.

## Смотрите также

- [Справочник банков](banks.md) — названия банков по странам.
- [Приём по СБП](sbp.md) — поля, статусы и крайние случаи, общие для всех методов.
- [API reference](api-reference.md#createPayment) — схема полей.