Общие правила

Все запросы — GET и POST с JSON. На этой странице собрано то, что одинаково для любого вызова: адреса, заголовки, формат списков и ошибок, единицы сумм. Параметры и примеры каждого метода — в разделах ниже.

Базовые адреса

# API продукта — только с вашего сервера
https://api.assalam.uz

# приём карты — из браузера или приложения
https://api.assalam.uz/checkout/v1

# страница привязки
https://checkout.assalam.uz

Всё, что авторизуется секретным ключом, вызывается только с вашего сервера. Исключение — ветка /checkout/v1: эти запросы идут из браузера или приложения клиента и авторизуются токеном сессии, а не ключом продукта.

Авторизация

Authorization: Bearer sk_live_...
Content-Type: application/json

# для создания заказов, списаний и возвратов
Idempotency-Key: order-1024

Ключ задаёт и режим, и объём доступа. sk_test_ работает с тестовым банком и не двигает деньги, sk_live_ — боевой; поля livemode в запросе нет. Область ключа ограничивает поверхность: ключ для продажи товаров не достаёт до карт клиентов, и наоборот — чужая поверхность отвечает 403. Подробнее — «Ключи и режимы».

Idempotency-Key

Заголовок обязателен для всего, что порождает обязательство: создание заказа, списание, возврат. Без него запрос отвергается.

• Повтор с тем же ключом и тем же телом возвращает сохранённый ответ — операция не выполняется второй раз.
• Тот же ключ с другим телом — 409. Иначе платёж на другую сумму тихо вернул бы результат старого.
• Значение выбираете вы, минимум 8 символов. Оно должно быть производным от вашего заказа, а не случайной строкой на каждый вызов: со случайной повтор после обрыва связи создаст второй платёж.

Подробнее — «Идемпотентность».

Суммы

Только целые числа в тийинах: 1 сум = 100 тийин, 50 000 сум передаются как 5000000. Дробных сумм не бывает. Минимум на операцию — 100, то есть один сум. Валюта одна — UZS.

Списки

{
  "object": "list",
  "data": [{ "id": "cmsr…", "object": "order", "status": "PAID" }],
  "has_more": false
}

Свежие записи сверху. Обход постраничный, по курсору: параметр starting_after с идентификатором последней полученной записи. limit — сколько вернуть за раз, до 100, по умолчанию 20.

Ошибки

Ошибка запроса — это HTTP-код 4xx или 5xx и объект error всегда одной формы: type — род ошибки, code — машинный код, message — объяснение для человека, param — поле, если ошибка относится к конкретному, и request_id.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "pan должен состоять из 16 цифр",
    "param": "pan",
    "request_id": "req_4f2c8a1b9d3e"
  }
}

Ветвитесь по type и code, а не по тексту message: текст мы можем уточнить в любой момент, коды — нет.

Отказ банка устроен иначе: запрос корректен, HTTP-ответ успешный, статус платежа FAILED, а причина — в failureCode. Это не сбой интеграции. Перечень кодов и что показывать клиенту — «Ошибки».

Разделы

Интерактивный справочник

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