API-справочник

Каждый запрос к /v1/* авторизуется секретным API-ключом. Ключ передаётся заголовком Authorization: Bearer или X-API-Key — обе формы равнозначны.

curl https://api.getyespay.com/v1/payments \
  -H "Authorization: Bearer sk_live_..."

# Эквивалентная форма:
curl https://api.getyespay.com/v1/payments -H "X-API-Key: sk_live_..."

• Ключ сам определяет режим: sk_live_… работает с настоящим Kaspi, sk_test_… — с мок-провайдером. Данные режимов полностью изолированы: тестовым ключом нельзя увидеть боевой платёж.
• Публикуемый ключ (pk_…) на /v1/* не принимается — в ответ придёт invalid_api_key с явным указанием, что нужен секретный ключ.
• Сессия кабинета не даёт доступа к /v1/*, а API-ключ не даёт доступа к /dashboard/*. Это разделение намеренное: XSS в кабинете не должен превращаться в возможность выставлять счета.

{
  "error": {
    "code": "payment_not_refundable",
    "message": "A payment in state \"pending\" cannot be refunded.",
    "type": "conflict",
    "details": { "status": "pending" }
  }
}

Заголовок Idempotency-Key поддерживают все запросы, которые двигают деньги: POST /v1/payments, POST /v1/invoices, POST /v1/refunds. Ключ — произвольная строка до 255 символов, уникальная в рамках вашего мерчанта.

# Первый запрос — счёт создан.
curl -X POST https://api.getyespay.com/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: ORDER-1001" \
  -H "Content-Type: application/json" \
  -d '{"amount":14990,"customer":{"phone":"+77001234567"},"order_id":"ORDER-1001"}'

# Тот же запрос ещё раз — тот же платёж, второго счёта нет.
# Ответ содержит заголовок: Idempotent-Replay: true

curl -X POST https://api.getyespay.com/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORDER-1001" \
  -d '{
    "amount": 14990,
    "currency": "KZT",
    "customer": { "phone": "+77001234567" },
    "description": "Заказ №1001",
    "order_id": "ORDER-1001",
    "method": "remote_invoice",
    "metadata": { "cart_id": "c_42" }
  }'

amountinteger, обязательно

Сумма целым числом тенге. Минимум 1, максимум 10 000 000. Дробные значения отклоняются.

currencystring

Только KZT (значение по умолчанию).

customer.phonestring, обязательно

Номер покупателя. Принимается в любом разумном виде (+7…, 8…, 10 цифр) и нормализуется в E.164.

descriptionstring

Назначение платежа, до 255 символов.

order_idstring

Ваш идентификатор заказа, до 128 символов. По нему потом удобно искать: GET /v1/payments?order_id=…

methodstring

remote_invoice (по умолчанию) — счёт прилетает покупателю в приложение Kaspi. qr — платёж по QR-коду.

metadataobject

Произвольный JSON, возвращается как есть в платеже и в вебхуках.

Ответ — 201 и объект платежа. Статус в момент создания — pending: счёт доставлен покупателю, оплаты ещё нет.

{
  "id": "pay_3Nq8xVb2...",
  "object": "payment",
  "status": "paid",
  "amount": 14990,
  "currency": "KZT",
  "order_id": "ORDER-1001",
  "description": "Заказ №1001",
  "customer": { "phone": "+77001234567" },
  "provider": "kaspi",
  "method": "remote_invoice",
  "receipt_url": "https://kaspi.kz/pay/receipt/...",
  "qr": null,
  "livemode": true,
  "refunded_amount": 0,
  "failure_code": null,
  "failure_message": null,
  "expires_at": "2026-09-07T09:00:00.000Z",
  "paid_at": "2026-09-06T09:01:12.000Z",
  "created_at": "2026-09-06T09:00:00.000Z",
  "metadata": { "cart_id": "c_42" }
}

receipt_urlstring | null

Ссылка на чек Kaspi. Появляется вместе с оплатой, до этого null.

qrobject | null

Для method: "qr": url — универсальный QR (его платят и приложения других банков), kaspi_app_url — прямая ссылка в приложение Kaspi.

refunded_amountinteger

Сколько уже возвращено по этому платежу, в тенге.

failure_code / failure_messagestring | null

Заполняются, когда платёж перешёл в failed.

provider_statusstring

Присутствует только при статусе unknown — сырой статус, который вернул Kaspi. Нужен поддержке для разбора.

livemodeboolean

false — платёж создан тестовым ключом.

Возвращает объект платежа. Чужой или несуществующий id — 404 resource_not_found.

statusstring

Фильтр по статусу, например paid.

order_idstring

Фильтр по вашему идентификатору заказа.

limitinteger

От 1 до 100, по умолчанию 25.

starting_afterstring

Курсор: id последнего элемента предыдущей страницы. Следующий курсор — в поле next_cursor.

Ответ: { "object": "list", "data": [...], "has_more": bool, "next_cursor": string | null }. Сортировка — от новых к старым.

• Отменяется только неоплаченный счёт. Финальный статус даёт 409 payment_not_cancellable.
• Уже оплаченный платёж отменить нельзя — нужен возврат, и API прямо об этом говорит.
• QR-платёж Kaspi отменить нельзя: придёт 501 provider_not_supported. Он гасится сам по истечении срока.

До 200 переходов в хронологическом порядке, вместе с сырым статусом провайдера. Это первое место, куда стоит смотреть при спорном платеже.

{
  "object": "list",
  "data": [
    { "id": "pev_1...", "from": null,      "to": "created", "reason": "created",           "provider_status": null,                  "created_at": "2026-09-06T09:00:00.000Z" },
    { "id": "pev_2...", "from": "created", "to": "pending", "reason": "provider_accepted", "provider_status": "RemotePaymentCreated", "created_at": "2026-09-06T09:00:01.000Z" },
    { "id": "pev_3...", "from": "pending", "to": "paid",    "reason": "provider_status",   "provider_status": "Processed",            "created_at": "2026-09-06T09:01:12.000Z" }
  ]
}

Счёт — документ для мерчанта, платёж — движение денег. Создание счёта создаёт и платёж: у Kaspi нет понятия «неотправленный счёт», поэтому черновик был бы обещанием, которого мы не сможем выполнить. Если вам не нужен отдельный документ, работайте напрямую с /v1/payments.

Тело — как у платежа, но без поля method (всегда remote_invoice). Ответ 201 содержит объект счёта и вложенный объект payment.

Отмена счёта отменяет и связанный платёж; ограничения те же, что у POST /v1/payments/:id/cancel.

curl -X POST https://api.getyespay.com/v1/refunds \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REFUND-ORDER-1001" \
  -d '{ "payment_id": "pay_3Nq8xVb2...", "reason": "Покупатель отказался" }'

payment_idstring, обязательно

Платёж в статусе paid или partially_refunded.

amountinteger

Опустите для полного возврата остатка. См. предупреждение ниже.

reasonstring

Причина, до 255 символов. Хранится у нас и видна в кабинете.

{
  "id": "ref_8Km2...",
  "object": "refund",
  "payment_id": "pay_3Nq8xVb2...",
  "status": "succeeded",
  "amount": 14990,
  "currency": "KZT",
  "reason": "Покупатель отказался",
  "failure_code": null,
  "failure_message": null,
  "created_at": "2026-09-06T10:00:00.000Z",
  "succeeded_at": "2026-09-06T10:00:02.000Z"
}

• Возврат синхронный: как правило, ответ уже содержит status: "succeeded".
• Сумма больше остатка — 409 refund_amount_exceeded с полем remaining в деталях.
• Платёж не в оплаченном состоянии — 409 payment_not_refundable.

Поддерживает фильтр payment_id и limit (1–100, по умолчанию 25).

Вебхук — то, как ваш бэкенд узнаёт об оплате. Postgres у нас источник правды, очередь — только ускоритель: если очередь упала, доставка всё равно произойдёт.

curl -X POST https://api.getyespay.com/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://shop.kz/webhooks/yespay",
    "events": ["payment.paid", "payment.failed", "payment.status_unknown"],
    "description": "Прод, основной обработчик"
  }'

urlstring, обязательно

Публичный https:// адрес. Приватные и служебные адреса отклоняются — и здесь, и на каждой доставке.

eventsstring[]

Список типов событий. Пустой список или отсутствие поля — присылать всё.

descriptionstring

Заметка для вашего же кабинета.

Меняются url, events, enabled, description.

Присылает событие webhook.test на все включённые эндпоинты текущего режима или на один, если передать { "webhook_id": "wh_…" }. Отвечает 202. Нужен, чтобы проверить свою проверку подписи до того, как от неё будет зависеть реальный платёж.

Статус каждой доставки, число попыток, HTTP-код вашего ответа, время следующей попытки и последняя ошибка. Фильтры: webhook_id, limit.

POST /webhooks/yespay HTTP/1.1
Content-Type: application/json
User-Agent: yespay-webhooks/1.0
X-Yespay-Signature: t=1757148037,v1=5f2c...c91
X-Yespay-Event-Id: evt_9F2K...
X-Yespay-Delivery-Id: whd_4Tz...
X-Yespay-Attempt: 1

{
  "id": "evt_9F2K...",
  "type": "payment.paid",
  "createdAt": "2026-09-06T09:01:12.000Z",
  "livemode": true,
  "data": {
    "id": "pay_3Nq8xVb2...",
    "object": "payment",
    "status": "paid",
    "amount": 14990,
    "currency": "KZT",
    "order_id": "ORDER-1001"
  }
}

import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.strip().split("=", 1) for p in header.split(","))
    timestamp = int(parts["t"])
    if abs(time.time() - timestamp) > tolerance:
        return False                      # слишком старое событие
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Секретные значения не возвращаются — только превью вида sk_live_abc…4f2a.

Принимает name и mode (test по умолчанию). Тестовым ключом нельзя создать боевой. Секрет возвращается один раз.

Инструкция по подключению — «Как подключить yespay». Готовые промты для ИИ-агентов — /docs/agents.