# Cross-border transfer

The payer in Russia pays in **rubles from their own bank**, and the requisite is a phone or a card
**in another country**, for example Tajikistan or Uzbekistan. The recipient gets the local currency
(somoni, sum); the payment side does the conversion. For you it is a ruble payment: the amount,
rate, fee and USDT credit work exactly as for [SBP](sbp.md) and [card transfer](card.md).

You do not choose the recipient country: the payment side chooses it and returns it in the
response. Show it to the payer so they know where the transfer goes.

<div class="pp-seq" data-lanes="Your server|API|Payer" markdown>

1. **Your server → API.** `POST /api/v1/payments` with `payment_method=cross_border_card` and `bank_code=Т-Банк` (the payer's bank)
2. **API.** Picks requisites for a transfer from this bank
3. **API ⇢ Your server.** `201`: `status=processing`, `requisite` — a phone or a card, `requisite_bank`, `cross_border_country`
4. **Your server → Payer.** The requisite, recipient, the recipient's bank and country, the amount in rubles and the deadline
5. **Payer.** Sends rubles from their bank app
6. **API → Your server.** Callback: `completed` or `canceled`

</div>

## Methods { #methods }

| `payment_method` | Requisite | How the client pays |
| --- | --- | --- |
| `cross_border_sbp` | phone number | a cross-border transfer by phone number |
| `cross_border_card` | card number | a transfer to a card in another country (c2c) |

The method must be in your project's contract, like `sbp` and `card_transfer`: check the
[contract limits](sbp.md#contract-limits) — they list entries with these methods.

## Payer's bank and fee { #payer-bank }

`bank_code` is the bank **the client pays from**, as for `sbp` and `card_transfer`: a name from the
[directory](banks.md) for `geo_code` (`Т-Банк`, `Сбер`, `Альфа`). The fee and the choice of the
payment side depend on the method and the bank: for example, `cross_border_card` + T-Bank and
`cross_border_sbp` + Sber are separate contract entries with their own fees. Without `bank_code` —
any bank, under the "any bank" entry.

The recipient country does not affect the fee: one contract entry covers transfers to both
Tajikistan and Uzbekistan.

## Create a payment { #create }

`POST /api/v1/payments` — a [signed](signing.md) request, as for other methods.

**From a specific bank** — with `bank_code` of the payer's bank:

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

**From any bank** — without `bank_code`:

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

### Fields { #fields }

| Field | Req. | Rules |
| --- | --- | --- |
| `payment_method` | yes | `cross_border_sbp` or `cross_border_card` |
| `geo_code` | no | The **payer's** country, default `RU` |
| `currency` | no | The **payer's** currency, default `RUB`: the payment amount is in it |
| `bank_code` | no | The **payer's** bank — a name from the [directory](banks.md) for `geo_code`, for example `Т-Банк`. Without it — any bank |
| `amount`, `merchant_payment_id`, `callback_url`, `client_id`, `client_username`, `client_ip` | — | As for [SBP](sbp.md#request-fields) |

The request has no recipient country: `cross_border_country` in the request is a `400` error.

## Response and callback { #response }

The response and callback are the same as for [SBP](sbp.md#response), plus `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` — a phone for `cross_border_sbp`, a card number for `cross_border_card`. Show it to
  the payer with `holder_name`, `requisite_bank` and the country: the payer picks the recipient's
  country and bank in their app.
- `cross_border_country` — the recipient country (`TJ` — Tajikistan, `UZ` — Uzbekistan) chosen by
  the payment side. It is absent until requisites are issued or when the country is unknown.
- `bank_code` — the payer's bank from the request; `requisite_bank` — the recipient's bank that
  issued the requisite.
- Payments of other methods do not have `cross_border_country`.

## Settlement { #settlement }

The payment is in rubles: `merchant_information` is the same [settlement](sbp.md#merchant-information)
at the USDT/RUB rate and your contract fee for the cross-border method and bank. The recipient
country's currency is not part of it.

## Errors { #errors }

| HTTP | `error` | When |
| --- | --- | --- |
| 400 | `bad_request` | The request has `cross_border_country` or another unknown field |
| 422 | `cross_border_invalid` | `bank_code` is a bank of another country, not the payer's bank of `geo_code` (for example a bank of Tajikistan) |
| 422 | `bank_not_found` | `bank_code` is not in the directory |
| 422 | `payment_not_covered` | The cross-border method and bank are not in your contract or the amount is out of range |
| 422 | `payment_not_routable` | A transfer from this bank cannot be accepted right now |

!!! warning "A bank of another country is an error"
    `bank_code` of any method is the payer's bank. A bank of Tajikistan or Uzbekistan in
    `bank_code` is rejected (`422 cross_border_invalid`): the payment side chooses the recipient's
    bank.

## See also

- [Bank directory](banks.md) — bank names by country.
- [SBP payments](sbp.md) — fields, statuses and edge cases shared by all methods.
- [API reference](api-reference.md#createPayment) — the field schema.