> For the complete documentation index, see [llms.txt](https://alfabit.gitbook.io/alfabit-pay/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alfabit.gitbook.io/alfabit-pay/rukovodstvo-po-integracii/oplata-zarubezhnykh-servisov.md).

# Оплата зарубежных сервисов

Данный функционал позволяет оплачивать иностранные игровые и digital-сервисы напрямую со своего баланса AlfaBit (как Личного, так и Бизнес), без использования банковских карт и внешних платёжных провайдеров.\
Оплата выполняется в автоматическом режиме через фиатный платёжный контур AlfaBit и по логике аналогична фиатному выводу: выбирается сервис, указывается сумма, система рассчитывает итог с учётом комиссии и создаёт платёжный заказ.

#### Доступные сервисы

На текущий момент доступны следующие зарубежные сервисы:

* **Steam** — оплата и пополнение аккаунтов Steam, непакетная услуга
* **Genshin Impact (Voucher)** — покупка ваучеров Genshin Impact, пакетная услуга
* **APEX Legends (Xbox)** — пополнение APEX Legends (платформа Xbox), пакетная услуга
* **Roblox EU** — пополнение Roblox (EU-регион), пакетная услуга
* **Minecraft** — пополнение Minecraft, пакетная услуга
* **PUBG: New State** — пополнение PUBG: New State, пакетная услуга
* **Call of Duty: Warzone** — пополнение Call of Duty Warzone, пакетная услуга
* **Blizzard (USA)** — пополнение сервисов Blizzard (регион USA), пакетная услуга

Каждый сервис представлен в API отдельным `serviceCode` и обрабатывается по единому сценарию интеграции. Добавление новых сервисов не требует изменений в логике интегратора — только использование нового кода сервиса.

#### Схема процесса оплаты зарубежного сервиса

Интеграция оплаты зарубежных сервисов в AlfaBit построена по трёхшаговой модели и полностью повторяет логику фиатного вывода.

**Шаг 1:**

## GET /api/v1/integration/merchant/fiat-config

> Получить список фиатных способов вывода и приема по всем валютам

```json
{"openapi":"3.0.0","info":{"title":"Интеграция API","version":"0.0.4.1-alpha"},"tags":[{"name":"api","description":""}],"paths":{"/api/v1/integration/merchant/fiat-config":{"get":{"operationId":"ApiMerchantController_getFiatConfig","summary":"Получить список фиатных способов вывода и приема по всем валютам","parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"    Эндпоинт позволяет получить список доступных способов для вывода и приема фиатных средств для мерчанта.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AResponseType"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ClientFiatSettingsSerializer"}}}}]}}}},"400":{"description":"Некорректный запрос","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomBadRequestException"}}}},"401":{"description":"Необходимо авторизоваться для запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomUnauthorizedException"}}}},"403":{"description":"Недостаточно прав","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomForbiddenException"}}}},"500":{"description":"Системная ошибка","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomInternalErrorException"}}}}},"tags":["api"]}}},"components":{"schemas":{"AResponseType":{"type":"object","properties":{"message":{"type":"string","description":"Сообщение статуса"},"data":{"type":"object","description":"Данные"},"count":{"type":"number","description":"Общее кол-во элементов в БД"}},"required":["message"]},"ClientFiatSettingsSerializer":{"type":"object","properties":{"name":{"type":"string","description":"Название"},"code":{"type":"string","description":"Код способа вывода"},"paymentMethod":{"type":"string","description":"Метод оплаты","enum":["card","phone","sbp","wallet","transgran","transgran_crypto","wire_transfer","bank_transfer","service"]},"currency":{"type":"string","description":"Валюта","enum":["RUB","USD","EUR","KZT","KGS","AZN","BYN","UZS","AMD","TRY","TJS"]},"currencyOutCode":{"type":"string","description":"Валюта на выходе (вывод с обменом)","enum":["RUB","USD","EUR","KZT","KGS","AZN","BYN","UZS","AMD","TRY","TJS"]},"paymentType":{"type":"string","description":"Тип платежного направления (прием/вывод)","enum":["deposit","withdraw"]},"providersOut":{"description":"Список провайдеров","type":"array","items":{"$ref":"#/components/schemas/ProviderOutSerializer"}},"providersIn":{"description":"Список провайдеров с которых можно платить (для deposit)","type":"array","items":{"$ref":"#/components/schemas/ProviderOutSerializer"}},"amountMin":{"type":"string","description":"Минимальная сумма"},"amountMax":{"type":"string","description":"Максимальная сумма"},"feePercent":{"type":"string","description":"Процент комиссии"},"isPackageService":{"type":"boolean","description":"Является ли услуга пакетной"},"requiredFields":{"type":"string","description":"Список обязательных полей","enum":["first_name","last_name","email","sender_first_name","sender_last_name"]},"categories":{"type":"string","description":"Список категорий","enum":["services","ps_games","xbox_games","gift_cards","new","top","others","phone","transfer_bank_card","internet","e_wallet","tv","education","gosuslugi","public_utilities","taxi","fun"]},"minFeeAmount":{"type":"string","description":"Минимальная сумма комиссии"},"additionalPercentForMinFee":{"type":"string","description":"Дополнительный процент комиссии, который применяется вместе с minFeeAmount"},"extraServiceFeeAmount":{"type":"string","description":"Фиксированная дополнительная сервисная комиссия","default":"0"}},"required":["name","code","paymentMethod","currency","providersOut","amountMin","amountMax","feePercent","isPackageService","requiredFields","categories","minFeeAmount","additionalPercentForMinFee"]},"ProviderOutSerializer":{"type":"object","properties":{"name":{"type":"string","description":"Название"},"code":{"type":"string","description":"Код"},"aliasCode":{"type":"string","description":"Код"},"method":{"type":"string","description":"Код метода вывода","enum":["card","phone","sbp","wallet","transgran","transgran_crypto","wire_transfer","bank_transfer","service"]}},"required":["name","code","aliasCode"]},"CustomBadRequestException":{"type":"object","properties":{"error":{"type":"string","description":"Описание ошибки"},"errorCode":{"type":"number","description":"Код ошибки"}},"required":["errorCode"]},"CustomUnauthorizedException":{"type":"object","properties":{"error":{"type":"string","description":"Описание ошибки"},"errorCode":{"type":"number","description":"Код ошибки"}},"required":["errorCode"]},"CustomForbiddenException":{"type":"object","properties":{"error":{"type":"string","description":"Описание ошибки"},"errorCode":{"type":"number","description":"Код ошибки"}},"required":["errorCode"]},"CustomInternalErrorException":{"type":"object","properties":{"error":{"type":"string","description":"Описание ошибки"},"errorCode":{"type":"number","description":"Код ошибки"}},"required":["errorCode"]}}}}
```

**Шаг 2:** Расчёт параметров оплаты сервиса (оценка)

Предварительный расчёт без создания реального заказа:

* проверяет корректность параметров,
* рассчитывает итоговую сумму и комиссию,
* возвращает параметры, которые будут использованы при создании платежа.

Результат используется для:

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

## POST /api/v1/integration/orders/estimate-fiat-service-in

> Оценка входа фиатного сервиса

```json
{"openapi":"3.0.0","info":{"title":"Интеграция API","version":"0.0.4.1-alpha"},"tags":[{"name":"api","description":""}],"paths":{"/api/v1/integration/orders/estimate-fiat-service-in":{"post":{"operationId":"ApiOrderController_estimateFiatServiceIn","summary":"Оценка входа фиатного сервиса","parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateFiatServiceInDto"}}}},"responses":{"200":{"description":"Успешная оценка входа фиатного сервиса","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AResponseType"},{"properties":{"data":{"$ref":"#/components/schemas/EstimationFiatServiceSerializer"}}}]}}}},"400":{"description":"Некорректный запрос","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomBadRequestException"}}}},"401":{"description":"Необходимо авторизоваться для запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomUnauthorizedException"}}}},"403":{"description":"Недостаточно прав","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomForbiddenException"}}}},"500":{"description":"Системная ошибка","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomInternalErrorException"}}}}},"tags":["api"]}}},"components":{"schemas":{"EstimateFiatServiceInDto":{"type":"object","properties":{"code":{"type":"string","description":"Код способа вывода"},"providerOutAliasCode":{"type":"string","description":"Услуга"},"requisites":{"type":"string","description":"Аккаунт зачисления"},"amount":{"type":"string","description":"Сумма к зачислению (для непакетных услуг)"}},"required":["providerOutAliasCode","requisites"]},"AResponseType":{"type":"object","properties":{"message":{"type":"string","description":"Сообщение статуса"},"data":{"type":"object","description":"Данные"},"count":{"type":"number","description":"Общее кол-во элементов в БД"}},"required":["message"]},"EstimationFiatServiceSerializer":{"type":"object","properties":{"rate":{"type":"string","description":"Курс (для непакетных услуг)"},"amount":{"type":"string","description":"Сумма"}},"required":["amount"]},"CustomBadRequestException":{"type":"object","properties":{"error":{"type":"string","description":"Описание ошибки"},"errorCode":{"type":"number","description":"Код ошибки"}},"required":["errorCode"]},"CustomUnauthorizedException":{"type":"object","properties":{"error":{"type":"string","description":"Описание ошибки"},"errorCode":{"type":"number","description":"Код ошибки"}},"required":["errorCode"]},"CustomForbiddenException":{"type":"object","properties":{"error":{"type":"string","description":"Описание ошибки"},"errorCode":{"type":"number","description":"Код ошибки"}},"required":["errorCode"]},"CustomInternalErrorException":{"type":"object","properties":{"error":{"type":"string","description":"Описание ошибки"},"errorCode":{"type":"number","description":"Код ошибки"}},"required":["errorCode"]}}}}
```

Заказ на втором шаге ещё не создаётся.

**Шаг 3:** Создание заявки на оплату сервиса

## POST /api/v1/integration/orders/fiat-payment-service-order

> Создание фиатного вывода сервиса

```json
{"openapi":"3.0.0","info":{"title":"Интеграция API","version":"0.0.4.1-alpha"},"tags":[{"name":"api","description":""}],"paths":{"/api/v1/integration/orders/fiat-payment-service-order":{"post":{"operationId":"ApiOrderController_createFiatPaymentServiceOrder","summary":"Создание фиатного вывода сервиса","parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFiatPaymentServiceOrderDto"}}}},"responses":{"200":{"description":"Успешное создание фиатного вывода сервиса","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AResponseType"},{"properties":{"data":{"$ref":"#/components/schemas/OrderSerializer"}}}]}}}},"400":{"description":"Некорректный запрос","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomBadRequestException"}}}},"401":{"description":"Необходимо авторизоваться для запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomUnauthorizedException"}}}},"403":{"description":"Недостаточно прав","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomForbiddenException"}}}},"500":{"description":"Системная ошибка","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomInternalErrorException"}}}}},"tags":["api"]}}},"components":{"schemas":{"CreateFiatPaymentServiceOrderDto":{"type":"object","properties":{"code":{"type":"string","description":"Код способа вывода"},"providerOutAliasCode":{"type":"string","description":"Услуга"},"requisites":{"type":"string","description":"Аккаунт зачисления"},"amount":{"type":"string","description":"Сумма к зачислению (для непакетных услуг)"},"callbackUrl":{"type":"string","description":"Callback url для отправки хуков","minLength":5},"comment":{"type":"string","description":"Комментарий к переводу. Опциональное поле"},"idempotencyKey":{"type":"string","description":"Ключ идемпотентности для предотвращения дублирования заявок при сетевых разрывах и состоянии гонки. Должен быть уникальным для каждого мерчанта.","maxLength":255}},"required":["providerOutAliasCode","requisites"]},"AResponseType":{"type":"object","properties":{"message":{"type":"string","description":"Сообщение статуса"},"data":{"type":"object","description":"Данные"},"count":{"type":"number","description":"Общее кол-во элементов в БД"}},"required":["message"]},"OrderSerializer":{"type":"object","properties":{"id":{"type":"number","description":"Id"},"uid":{"type":"string","description":"UUID"},"createdAt":{"format":"date-time","type":"string","description":"Дата создания"},"updatedAt":{"format":"date-time","type":"string","description":"Дата обновления"},"deletedAt":{"format":"date-time","type":"string","description":"Дата удаления"},"serviceCommission":{"type":"string","description":"Комиссия сервиса"},"netCommission":{"type":"string","description":"Комиссия сети"},"comment":{"type":"string","description":"Комментарий"},"publicComment":{"type":"string","description":"Публичный комментарий"},"merchantUid":{"type":"string","description":"UUID мерчанта"},"merchantName":{"type":"string","description":"Имя мерчанта"},"merchantId":{"type":"string","description":"ID мерчанта"},"type":{"type":"string","description":"Тип заявки","enum":["deposit","invoice","invoice-without-amount","payment","payment-without-amount","exchange","withdraw","withdraw-with-exchange","account-transfer","currency-to-currency","account-deposit","ref-payment"]},"status":{"type":"string","description":"Статус заявки","enum":["created","success","warning","failed","inProgress","invoiceWaitCreate","invoiceNotCreated","invoiceWaitRequisites","invoiceWaitPay","invoiceWaitConfirms","invoiceWaitCheck","invoiceNotPayed","invoiceCheckBlocked","transferBlocked","exchangeBlocked","withdrawBlocked","waitRefundRequisites","waitRefundRequisitesCheck","waitToRefund","refunded","revoked"]},"invoiceCurrencyCode":{"type":"string","description":"Валюта, в которой выставлен инвойс"},"currencyInCode":{"type":"string","description":"Валюта оплаты"},"currencyOutCode":{"type":"string","description":"Получаемая валюта"},"invoiceAmount":{"type":"string","description":"Сумма инвойса"},"amountInExpected":{"type":"string","description":"Ожидаемая сумма оплаты"},"amountInFact":{"type":"string","description":"Фактическая сумма оплаты"},"amountOutExpected":{"type":"string","description":"Ожидаемая получаемая сумма"},"amountOutFact":{"type":"string","description":"Фактическая получаемая сумма"},"hedgeRate":{"type":"string","description":"Курс хеджирования"},"isDone":{"type":"boolean","description":"Заявка завершена?"},"apiMode":{"type":"string","description":"Источник создания заявки (UI | API)","enum":["ui","api","gateway"]},"risk":{"type":"string","description":"Оценка риска"},"requisites":{"type":"string","description":"Реквизиты заявки"},"requisitesIn":{"type":"string","description":"Реквизиты заявки вход"},"requisitesOut":{"type":"string","description":"Реквизиты заявки выход"},"requisitesMemoTag":{"type":"string","description":"Мемо тег (для XRP, TON и т.д.)"},"requisitesMemoTagIn":{"type":"string","description":"Мемо тег вход (для XRP, TON и т.д.)"},"requisitesMemoTagOut":{"type":"string","description":"Мемо тег выход (для XRP, TON и т.д.)"},"billingTag":{"type":"string","description":"Биллинг тэг"},"requisitesQrCode":{"type":"string","description":"Ссылка на QR с реквизитами"},"assetInCode":{"type":"string","description":"Входящий ассет"},"assetOutCode":{"type":"string","description":"Исходящий ассет"},"networkInCode":{"type":"string","description":"Входящяя сеть ассета"},"networkOutCode":{"type":"string","description":"Исходящяя сеть ассета"},"balanceAfter":{"type":"string","description":"Баланс после завершения заявки"},"balanceAccountAfter":{"type":"string","description":"Баланс после завершения заявки в ledger"},"callbackUrl":{"type":"string","description":"Колбэк урл"},"invoicePublicUrl":{"type":"string","description":"Публичный урл инвойса"},"txId":{"type":"string","description":"Айди транзакции"},"refundTxId":{"type":"string","description":"Айди транзакции возврата"},"expirationTime":{"format":"date-time","type":"string","description":"Оплатить до"},"isImPayed":{"type":"boolean","description":"Нажал оплатил?"},"isBayerPaysService":{"type":"boolean","description":"Покупатель оплачивает сервисную комиссию инвойсов?"},"serviceFeeCurrencyCode":{"type":"string","description":"Валюта оплаты комиссии сервиса"},"netFeeCurrencyCode":{"type":"string","description":"Валюта возмещения комиссии сети"},"requisitesInUrl":{"type":"string","description":"Ссылка для оплаты от внешнего платежного провайдера"},"orderCurrencyType":{"type":"string","description":"Тип валют участвующих в операции","enum":["fiat","crypto","fiatToCrypto","cryptoToFiat"]},"paymentMethod":{"type":"string","description":"Платежный метод","enum":["card","phone","sbp","wallet","transgran","transgran_crypto","wire_transfer","bank_transfer","service"]},"providerCode":{"type":"string","description":"Код фиатного провайдера"},"providerAliasCode":{"type":"string","description":"Человекочитаемый код фиатного провайдера"},"paymentSettingsName":{"type":"string","description":"Название фиатной настройки"},"providerName":{"type":"string","description":"Название фиатного провайдера"},"amlReportExists":{"type":"boolean","description":"Существует AML отчет по ордеру?"},"minFeeTriggerAmount":{"type":"string","description":"Порог, на котором изменяется принцип рассчета комиссии"},"paymentTiming":{"type":"string","description":"Оплата во время или после просрочки","enum":["onTime","afterDue"]},"amountValidity":{"type":"string","description":"Валидность суммы платежа","enum":["less","valid","greater"]},"signature":{"type":"string","description":"Подпись запроса в хуке (для проверки подлинности)"},"warningCode":{"type":"string","description":"Код предупреждения"},"giftCode":{"type":"string","description":"Код активации услуги"},"extraInfo":{"description":"Дополнительная информация из первого хопа","type":"array","items":{"type":"string"}}},"required":["id","uid","createdAt","updatedAt","deletedAt","serviceCommission","netCommission","comment","publicComment","merchantUid","merchantName","merchantId","type","status","invoiceCurrencyCode","currencyInCode","currencyOutCode","invoiceAmount","amountInExpected","amountInFact","amountOutExpected","amountOutFact","hedgeRate","isDone","apiMode","risk","requisites","requisitesIn","requisitesOut","requisitesMemoTag","requisitesMemoTagIn","requisitesMemoTagOut","billingTag","requisitesQrCode","assetInCode","assetOutCode","networkInCode","networkOutCode","balanceAfter","balanceAccountAfter","callbackUrl","invoicePublicUrl","txId","refundTxId","expirationTime","isImPayed","isBayerPaysService","serviceFeeCurrencyCode","netFeeCurrencyCode","requisitesInUrl","orderCurrencyType","amlReportExists","paymentTiming","amountValidity","signature","warningCode","giftCode","extraInfo"]},"CustomBadRequestException":{"type":"object","properties":{"error":{"type":"string","description":"Описание ошибки"},"errorCode":{"type":"number","description":"Код ошибки"}},"required":["errorCode"]},"CustomUnauthorizedException":{"type":"object","properties":{"error":{"type":"string","description":"Описание ошибки"},"errorCode":{"type":"number","description":"Код ошибки"}},"required":["errorCode"]},"CustomForbiddenException":{"type":"object","properties":{"error":{"type":"string","description":"Описание ошибки"},"errorCode":{"type":"number","description":"Код ошибки"}},"required":["errorCode"]},"CustomInternalErrorException":{"type":"object","properties":{"error":{"type":"string","description":"Описание ошибки"},"errorCode":{"type":"number","description":"Код ошибки"}},"required":["errorCode"]}}}}
```