API выпуска подарочных карт

1. 1

   Откройте вкладку «Токены выпуска»

   Войдите в аккаунт, откройте страницу «Подарочные карты и прямое пополнение», перейдите на вкладку «Токены выпуска» и нажмите «Новый токен выпуска».

2. 2

   Укажите название и необязательные ограничения

   Название — до 60 символов, например «Магазин цифровых товаров». Белый список IP и дневной лимит необязательны; если оставить их пустыми, ограничений нет. Платформа не задаёт значений по умолчанию.

3. 3

   Сразу сохраните токен

   Токен начинается с wkt_ и показывается только один раз. Если потеряете его — отзовите и создайте новый. При создании токена приходят уведомление на сайте и письмо.

Base URL

https://wokey.ai/api/issuer/v1

Авторизация

Передавайте Authorization: Bearer wkt_… в каждом запросе. Сессия входа на сайте не может вызывать эти эндпоинты, а токен выпуска не может вызывать никакие другие.

Запросы и ответы

Тела запросов и ответов — JSON. Суммы в ответах — строки с двумя знаками после точки (например, "10.00"), время — ISO 8601 в UTC.

curl -X POST https://wokey.ai/api/issuer/v1/codes \
  -H "Authorization: Bearer wkt_YOUR_ISSUING_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20261017-0001" \
  -d '{ "sourceType": "provider", "amountUsd": 10, "count": 1, "label": "order-20261017-0001" }'

{
  "batch": {
    "id": "icb_…",
    "sourceType": "provider",
    "amountUsd": "10.00",
    "count": 1,
    "totalUsd": "10.00",
    "label": "order-20261017-0001",
    "createdAt": "2026-10-17T08:00:00.000Z"
  },
  "replayed": false,
  "codes": [
    {
      "id": "ic_…",
      "batchId": "icb_…",
      "kind": "code",
      "sourceType": "provider",
      "amountUsd": "10.00",
      "codeHint": "7K2M",
      "status": "active",
      "label": "order-20261017-0001",
      "createdAt": "2026-10-17T08:00:00.000Z",
      "redeemedAt": null,
      "redeemedByMaskedEmail": null,
      "voidRequestedAt": null,
      "voidEffectiveAt": null,
      "voidedAt": null,
      "frozenAt": null,
      "code": "WK-4F9Q-T3XA-8HRB-7K2M",
      "redeemUrl": "https://wokey.ai/redeem#WK-4F9Q-T3XA-8HRB-7K2M"
    }
  ]
}

code — код активации, redeemUrl — ссылка для активации; отправьте покупателю любой из них. Покупатель активирует карту после входа в Wokey, и номинал зачисляется на его API-кредиты.

• Для создания карт и прямых пополнений ключ идемпотентности обязателен. Удобно использовать ID заказа.
• Ключи уникальны в пределах аккаунта и общие для сайта и API выпуска, независимо от того, какой токен отправил запрос.
• Повтор запроса с тем же ключом и теми же параметрами ничего не списывает и возвращает первый результат с replayed = true; повтор создания снова возвращает те же коды.
• Тот же ключ с другими параметрами (sourceType, amountUsd, count, а для прямого пополнения — получатель) возвращает 409 idempotency_key_conflict.
• После сетевого таймаута или ответа 5xx повторите запрос с тем же ключом — двойного списания не будет.

• Создание карт и прямые пополнения: не более 60 в минуту на аккаунт (сайт и API выпуска вместе).
• Чтение данных карты (с кодом): не более 120 в минуту на аккаунт.
• Не более 500 карт в пачке; номинал одной карты — от 1 до 1 000 000 USD.
• Не более 20 неотозванных токенов выпуска на аккаунт и не более 20 IP в белом списке каждого токена.

Рекомендации по безопасности

• Храните токен только на сервере (в бэкенде магазина или на своём сервере). Не размещайте его во фронтенде сайта, в приложении или в публичном репозитории.
• Если у вас фиксированный исходящий IP, задайте белый список. Записи сравниваются с IP точно; диапазоны не поддерживаются.
• Задайте дневной лимит, чтобы ограничить потери при утечке токена. Лимит считает карты и прямые пополнения вместе за сутки UTC.
• Смена пароля или выход из всех сессий не отзывает токены выпуска. Если подозреваете утечку, отзовите токен на вкладке «Токены выпуска» — он сразу перестанет работать.
• На вкладке «Токены выпуска» видно, когда и с какого IP каждый токен использовался последний раз. Проверяйте это время от времени.