Разработчикам

Подключение за три шага

• В кабинете откройте магазин и выпустите ключ API в разделе «API». Для счетов хватит доступа «Только счета», полный нужен для выплат. Ключ покажут один раз, храните его на сервере.
• Укажите адрес вебхука в разделе «Вебхук» и сохраните ключ подписи.
• Выставьте счёт и отправьте покупателя по ссылке pay_url из ответа.

Счёт одним запросом

curl -X POST https://<домен>/api/v1/invoices \
  -H "Authorization: Bearer cpk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{"currency": "USD", "amount": "49.90", "reference": "order-1042"}'

Если запрос повторится с тем же Idempotency-Key, второго счёта не будет. Суммы передаются строками, время в UTC.

События

• payment.seen, payment.detected, payment.confirmed, payment.orphaned: платёж замечен, найден в блоке, зачислен, откатился
• invoice.paid, invoice.partially_paid, invoice.expired, invoice.cancelled: состояние счёта
• payout.broadcast, payout.confirmed, payout.failed: выплата отправлена, подтверждена, не удалась

Событие принято, если ваш сервер ответил кодом 2xx за 10 секунд. Иначе CoinsPay повторит его с растущей паузой: 20 попыток примерно за сутки.

Проверка подписи

import crypto from 'node:crypto';

// rawBody — тело запроса ровно как пришло, до JSON.parse.
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Примеры на Go, PHP и Python есть в кабинете, в разделе «Вебхук», и в документации API.

Ограничения

• До 600 запросов в минуту с одного IP.
• До 60 запросов в минуту на магазин, отдельно для адресов, счетов и выплат.
• Все методы и поля описаны в документации API.