Документация/Начало/Быстрый старт
Быстрый старт
Основной сценарий: карточные данные собирает страница оплаты платформы и не проходят через ваш backend. Ниже — путь, по которому идёт боевая интеграция.
1. Получите доступы
В кабинете dashboard.calibripay.com создайте API-ключ. secret_key показывается один раз и восстановлению не подлежит — только ротации. Заведите отдельный ключ на каждый сервис и держите секрет в серверном secret manager, а не в репозитории.
Прежде чем создавать первую операцию, сверьте нужные валюту и метод оплаты с возможностями канала — они же определяют, будут ли доступны возврат и раздельное списание.
# Base URL
https://api.calibripay.com/api/v1
# ключи — из secret manager, не из репозитория
CALIBRIPAY_ACCESS_KEY=<access_key>
CALIBRIPAY_SECRET_KEY=<secret_key>2. Создайте оплату
Backend мерчанта отправляет подписанный запрос (как подписывать):
Запрос
POST /api/v1/payment-sessions
Idempotency-Key: order-20260817-001
{
"order_id": "order-20260817-001",
"amount_minor": 1001,
"currency": "EUR",
"customer": { "email": "anna.schmidt@example.test" },
"return_url": "https://merchant.example.com/payments/return",
"locale": "en"
}Ответ 201
{
"payment_id": "0198c5f2-7b3e-7a41-9c2d-3f8a1b6e4d02",
"status": "awaiting_payment_data",
"final": false,
"checkout_url": "https://pay.calibripay.com/p/opaque-token",
"expires_at": "2026-08-17T13:15:22Z"
}3. Отправьте плательщика на checkout_url
Ссылка одноразовая и истекает в expires_at. Открывайте её полным переходом браузера: не меняйте URL, не извлекайте из него токен и не отправляйте карточные данные в Client API из браузера. Страница оплаты сама соберёт поля, определит схему карты, проведёт 3-D Secure и покажет итог.
Возврат браузера ≠ оплата
Возврат на return_url не подтверждает успех. Итоговый статус приходит вебхуком или запрашивается по GET /payments/{payment_id}.
4. Получите итоговый статус
Подпишитесь на вебхуки — это основной канал изменений. Запрос статуса нужен для восстановления после пропущенной доставки, сверки и контрольного чтения перед выдачей товара; расписание опроса и полная таблица состояний — на странице статусов.
Критерий успеха
Оплата успешна только при status="succeeded" и final=true одновременно. Любой ответ с final=false — не успех.