# Assalam — платёжная платформа

Приём платежей с карт в Узбекистане. Валюта одна — узбекский сум (UZS).

Две поверхности под разные задачи:
- Checkout API (/merchant/v1/orders) — продажа товаров: заказ, ссылка
  на оплату, событие об исходе. О картах знать не нужно.
- Subscribe API (/subscribe/v1/...) — карты и списания: клиент привязывает
  карту один раз, дальше списываете сами.

Базовый адрес API: https://api.assalam.uz
Машиночитаемая спецификация OpenAPI: https://api.assalam.uz/api-docs-json
Интерактивный справочник: https://api.assalam.uz/api-docs

## Обязательно знать до написания кода

- ПОВЕРХНОСТЕЙ ДВЕ, выберите одну. Продаёте товары — Checkout API
  (/merchant/v1/orders): создаёте заказ, отправляете покупателя по ссылке,
  получаете событие; карт не касаетесь вовсе. Списываете с сохранённой карты
  (подписки, пополнения) — Subscribe API (/subscribe/v1/...). Внутри платформа
  одна, различается объём знаний, который нужен интегратору.
- ВОЗВРАТ ДЕНЕГ НА КАРТУ СЕЙЧАС НЕВОЗМОЖЕН. Банк не передал эту операцию:
  POST /v1/refunds отвечает NOT_SUPPORTED. Не генерируйте сценарии с возвратом
  как с рабочим шагом. Возвраты оформляются на стороне банка вручную.
- Область ключа ограничивает доступ: ключ Checkout не достаёт до карт,
  ключ Subscribe — до заказов. Чужая поверхность отвечает 403 и называет обе
  области. События, баланс и возвраты доступны любому ключу.
- Суммы — целые числа в тийинах. 1 сум = 100 тийин, 50 000 сум = 5000000.
  Дробных сумм не бывает; передача 50000.50 — ошибка.
- Заголовок Idempotency-Key обязателен для всего, что порождает обязательство:
  создание заказа, списание, возврат. Без него запрос отвергается. Повтор
  с тем же ключом возвращает прежний результат, тот же ключ с другим телом —
  ошибку.
- Режим определяется КЛЮЧОМ, а не полем запроса: sk_test_* — тестовый,
  sk_live_* — боевой. Поля livemode в запросе нет.
- Номер карты не должен попадать на сервер продукта. На поверхности Checkout
  этим занимается наша страница оплаты; на Subscribe — сессия привязки
  POST /subscribe/v1/card_sessions. Серверный приём номера выключен
  по умолчанию и включается отдельным решением.
- Прежние адреса /v1/payment_methods, /v1/payment_intents и
  /v1/checkout_sessions продолжают работать и ведут в тот же код. В новом коде
  используйте /subscribe/v1/cards, /subscribe/v1/charges и
  /subscribe/v1/card_sessions.
- Списки возвращают { object: "list", data: [...], has_more: bool }.
  Следующая страница — параметр starting_after с id последней записи.
- Ошибка всегда одной формы: { error: { type, code, message, param?,
  request_id } }. Ветвитесь по type и code, не по тексту message.
- Вебхуки подписаны заголовком Assalam-Signature: t=<время>,v1=<hmac-sha256>.
  Подписывается строка "<t>.<сырое тело>". Проверяйте до разбора JSON.
- Фискальный чек выпускает банк-эквайер на своей стороне, платформа его
  не формирует. Поля состава заказа в платёжных вызовах нет; передавать
  items не нужно.

## Разделы


- **Начало**
- [Обзор](https://docs.assalam.uz/): Приём платежей с банковских карт Узбекистана. Два способа подключения — выберите свой, читать оба не нужно.
- [Как это устроено](https://docs.assalam.uz/model): Объекты платформы, идентификаторы и кто что хранит
- [Ключи и режимы](https://docs.assalam.uz/authentication): Ключи sk_test и sk_live, области действия, тестовый и боевой режим
- [Идемпотентность](https://docs.assalam.uz/idempotency): Повтор запроса не спишет деньги дважды

- **Продажа товаров**
- [Приём оплаты за четыре шага](https://docs.assalam.uz/checkout): Заказ, ссылка на оплату и событие об исходе
- [Заказы](https://docs.assalam.uz/orders): Создание, состояния, события и отмена заказа

- **Карты и списания**
- [Первое списание за пять шагов](https://docs.assalam.uz/quickstart): От привязки карты до денег на балансе
- [Привязка карты](https://docs.assalam.uz/cards): Наша страница привязки или своя форма — и почему номер карты не должен попадать на ваш сервер
- [Списания](https://docs.assalam.uz/payments): Списание с привязанной карты, подтверждение и статусы

- **Общее для обеих**
- [Вебхуки](https://docs.assalam.uz/webhooks): Узнавать о событиях, не опрашивая нас: подпись, повторы, типы событий
- [Тестирование](https://docs.assalam.uz/testing): Тестовые карты, коды подтверждения и сценарии отказов
- [Ошибки](https://docs.assalam.uz/errors): Форма ответа об ошибке, коды отказов и что показывать клиенту
- [Чего пока нельзя](https://docs.assalam.uz/limits): Возврат на карту и другие пределы платформы

- **Справочник**
- API Reference: Все эндпоинты и параметры
  - [Общие правила](https://docs.assalam.uz/api): Адреса, заголовки, идемпотентность, формат списков и ошибок — одинаково во всех вызовах
  - [Заказы](https://docs.assalam.uz/api/orders): Создание заказа, чтение, отмена
  - [Сессии привязки карты](https://docs.assalam.uz/api/checkout-sessions): Создание сессии и чтение её состояния
  - [Приём карты от клиента](https://docs.assalam.uz/api/checkout-public): Публичные вызовы страницы оплаты — без секретного ключа
  - [Карты](https://docs.assalam.uz/api/payment-methods): Список привязанных карт, чтение и отвязка
  - [Списания](https://docs.assalam.uz/api/payment-intents): Создание списания, подтверждение, чтение и список
  - [Возвраты](https://docs.assalam.uz/api/refunds): Метод существует, но банк операцию не передал
  - [Баланс](https://docs.assalam.uz/api/balance): Сколько денег на балансе продукта и из чего он складывается
- [Интеграция с агентом](https://docs.assalam.uz/agents): Машиночитаемая документация — llms.txt, llms-full.txt и OpenAPI

## Полный текст

- [Вся документация одним файлом](https://docs.assalam.uz/llms-full.txt)