Документация API

Быстрый старт

Первый запрос

Подключите свой сайт к платежам FastPay. Начните с тестового ключа — без реальных оплат.

1. 1

   Создайте ключ

   В разделе «Интеграции» выберите тестовый режим и права payments:read и payments:write.

2. 2

   Сохраните на сервере

   Задайте FASTPAY_API_KEY в переменных окружения. Для FASTPAY_BASE_URL используйте адрес FastPay, например https://fastpay.ink.

3. 3

   Проверьте подключение

   Запрос ниже вернёт бизнес и эффективный режим этого ключа. Он не создаёт платежей.

curl "$FASTPAY_BASE_URL/api/v1/account" \
  -H "Authorization: Bearer $FASTPAY_API_KEY"

Примеры только копируются. Эта страница не отправляет API-запросы.

Доступ

Один ключ — одно подключение.

Передавайте ключ в заголовке Authorization: Bearer …. Ключ привязан к бизнесу и режиму, выбранному при создании.

Создание

Счёт на телефон или QR.

Отправьте POST /api/v1/payments с правом payments:write. Сумма передаётся в тенге, не в тиынах.

curl -X POST "$FASTPAY_BASE_URL/api/v1/payments" \
  -H "Authorization: Bearer $FASTPAY_API_KEY" \
  -H "Idempotency-Key: order-42-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "qr",
    "amount": 100,
    "currency": "KZT",
    "externalOrderId": "ORDER-42"
  }'

Ответ содержит data.id и data.status. При создании QR также возвращается data.qrCodeDataUrl.

Тестовый режим

Проведите платёж от создания до возврата.

Тестовый QR открывает безопасную страницу FastPay и сам не меняет статус. Задайте результат через API или в деталях платежа в кабинете. Ни один из этих шагов не обращается в Kaspi.

1. 1

   Создайте платёж

   Выполните запрос из раздела выше и сохраните data.id как PAYMENT_ID.

2. 2

   Имитируйте оплату

   Передайте один из результатов: paid, failed, expired или cancelled.

3. 3

   Проверьте интеграцию

   Получите платёж через API и убедитесь, что вебхук принял соответствующее событие.

4. 4

   Проверьте возврат

   После результата paid верните тестовую сумму без подключения Kaspi.

curl -X POST "$FASTPAY_BASE_URL/api/v1/payments/PAYMENT_ID/simulate-status" \
  -H "Authorization: Bearer $FASTPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"paid"}'

curl -X POST "$FASTPAY_BASE_URL/api/v1/payments/PAYMENT_ID/refunds" \
  -H "Authorization: Bearer $FASTPAY_API_KEY" \
  -H "Idempotency-Key: refund-order-42-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"amount":100}'

Результат

Проверяйте статус, а не скриншот.

Замените PAYMENT_ID на data.id созданного платежа.

curl "$FASTPAY_BASE_URL/api/v1/payments/PAYMENT_ID" \
  -H "Authorization: Bearer $FASTPAY_API_KEY"

unknown не подтверждает оплату — дождитесь уточнения. Возвраты: partially_refunded или refunded.

Полный сценарий имитации оплаты и возврата приведён в разделе «Тестовый цикл».

Уведомления

Получайте изменения автоматически.

Добавьте webhook URL в настройках ключа. FastPay отправляет на него POST с событием и данными платежа. Сохраните отдельный секрет подписи webhook на сервере.

1. Проверьте X-Webhook-Timestamp и подпись X-Webhook-Signature по исходному телу запроса.
2. Обработайте событие один раз: используйте X-Webhook-Id для защиты от повторов.
3. После сохранения события верните ответ 2xx.

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody is the original body Buffer, before JSON.parse.
export function verifyWebhook(headers, rawBody, secret) {
  const timestamp = headers['x-webhook-timestamp'];
  const signature = headers['x-webhook-signature'];
  if (typeof timestamp !== 'string' ||
      typeof signature !== 'string' ||
      !/^\d+$/.test(timestamp) ||
      !/^sha256=[a-f0-9]{64}$/.test(signature)) return false;

  // A five-minute window is the receiver policy.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300)
    return false;

  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(timestamp + '.').update(rawBody).digest('hex');
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Подпись: sha256= + hex HMAC-SHA256 от timestamp + "." + rawBody. Не вычисляйте подпись по повторно сериализованному JSON. X-Webhook-Delivery обозначает доставку, а не уникальное событие.

Отладка

Если запрос не прошёл.

Ответ ошибки содержит error и может содержать requestId. Сохраните requestId для разбора ошибки; API-ключ в логи не записывайте.

API v1

Все методы.

Общий префикс — /api/v1. Полные схемы запросов и ответов — в OpenAPI.

Методы не найдены. Попробуйте другой запрос.