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

Создайте счёт, откройте оплату и подтвердите результат на своём сервере.

Этот сценарий проводит один заказ через весь платёжный путь. Для него нужны API-ключ проекта, HTTPS-адрес вебхука и сервер, на котором секреты не попадают в клиентский код.

1. Сохраните секреты

.env

PLATESHKA_API_KEY=plt_...
PLATESHKA_WEBHOOK_SECRET=whsec_...

Не добавляйте .env в репозиторий. Если ключ оказался в браузере, логе или публичном файле, перевыпустите его.

2. Создайте счёт

Idempotency-Key связывает запрос с вашим заказом. Сохраните ключ до первого вызова и используйте тот же при сетевом сбое или повторном запуске задачи.

curl -X POST https://api.plateshka.xyz/v1/invoices \
  -H "Authorization: Bearer $PLATESHKA_API_KEY" \
  -H "Idempotency-Key: order-4815162342" \
  -H "Content-Type: application/json" \
  -d '{"amount":{"amount":"149900","currency":"RUB"},"metadata":{"orderId":"4815162342"}}'

3. Откройте оплату

Сохраните invoice.id, затем перенаправьте покупателя на invoice.paymentUrl. Не собирайте ссылку самостоятельно: её единственный источник — ответ API.

return new Response(null, {
  status: 302,
  headers: { location: invoice.paymentUrl },
});

4. Подтвердите результат

Настройте вебхук и выдавайте заказ только по invoice.success. returnUrl можно использовать для экрана результата, но не как доказательство оплаты.

import { parseWebhookEvent } from '@plateshka/sdk';

const event = parseWebhookEvent(rawBody, signature, process.env.PLATESHKA_WEBHOOK_SECRET!);

if (event.type === 'invoice.success') {
  await fulfillOnce(event.id, event.data.invoice.metadata.orderId);
}

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

401 означает проблему с ключом, 422 — недоступный способ оплаты или неверные поля, 429 — превышенный лимит. При обрыве связи повторите создание с тем же ключом и тем же телом.

Следующий шаг

Разберите статусы счёта, затем соберите устойчивый обработчик вебхуков.