API платежей

Аутентификация

Создайте ключ в разделе «Приём оплаты» → «API и webhook» (в аккаунте должна быть включена двухэтапная проверка). Передавайте его в заголовке Authorization и храните только на сервере. Выберите доступ: «чтение и создание платежей» (магазин) или «только чтение» (сверка, отчёты). Ключ только для чтения при попытке создания получит 403.

Authorization: Bearer ib_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Создать платёж

token: USDC или SOL. valor: десятичное число с точкой; не указывайте для свободной суммы. validade_horas: 1, 24, 72, 168 или 720 (по умолчанию 24). externo_id: номер заказа в вашем магазине, уникальный в пределах аккаунта. Передавайте Idempotency-Key (UUID), чтобы безопасно повторить запрос при сбое сети.

curl -X POST https://ducripto.com/api/v1/cobrancas \
  -H "Authorization: Bearer ib_XXXXXXXXXXXX_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a8e-4b1d-4c55-9a3e-0d2b7f9e1c11" \
  -d '{"token":"USDC","valor":"25.90","descricao":"Pedido 1042","externo_id":"1042","validade_horas":24}'

{
  "id": "9b2f…", "estado": "pendente", "externo_id": "1042",
  "token": "USDC", "decimais": 6, "valor_unidades": "25900000", "valor": "25.9",
  "url_pagamento": "https://ducripto.com/pagar/9b2f…",
  "solana_pay": "solana:<carteira>?amount=25.9&spl-token=EPjF…&reference=…",
  "expira_em": "…", "pagamento": null
}

Запрос

Суммы всегда возвращаются строкой в целых единицах токена (valor_unidades), без потери точности. estado: pendente, paga, expirada или cancelada. Список возвращается постранично: используйте limite (от 1 до 100, по умолчанию 50) и передайте в depois значение proximo, чтобы получить следующую страницу; proximo = null — конец. Для кошельков, которые собирают транзакцию на сервере (Solana Pay «transaction request»), используйте solana_pay_transacao; для платежа со свободной суммой добавьте ?quantidade= к URL перед кодированием.

curl https://ducripto.com/api/v1/cobrancas/9b2f… -H "Authorization: Bearer ib_…"
curl "https://ducripto.com/api/v1/cobrancas?externo_id=1042" -H "Authorization: Bearer ib_…"
curl "https://ducripto.com/api/v1/cobrancas?limite=50&depois=<proximo>" -H "Authorization: Bearer ib_…"

Webhook: платёж оплачен

Вы получаете POST JSON с типом cobranca.paga. Проверьте подпись: HMAC-SHA256 в hex от «timestamp.тело» с вашим секретом, и отклоняйте запрос, если timestamp старше 5 минут. Отвечайте 2xx; иначе мы повторяем отправку с нарастающей паузой. Используйте evento_id, чтобы игнорировать повторы.

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

// corpo = texto CRU da requisição (antes de JSON.parse)
// x-interbank-assinatura-anterior só vem durante uma troca de chaves da plataforma: aceite qualquer uma
export function webhookValido(corpo, cab, segredo) {
  const ts = cab['x-interbank-timestamp'];
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const esperado = createHmac('sha256', segredo).update(`${ts}.${corpo}`).digest();
  return ['x-interbank-assinatura', 'x-interbank-assinatura-anterior'].some((h) => {
    const veio = Buffer.from(cab[h] ?? '', 'hex');
    return veio.length === esperado.length && timingSafeEqual(veio, esperado);
  });
}

Кнопка оплаты на вашем сайте (SDK)

Одна строка скрипта отрисовывает кнопку с вашим брендом и открывает страницу оплаты в новой вкладке; после подтверждения оплаты ваш сайт получает событие checkout:paga. Это событие только для интерфейса: выдавайте заказ после проверки на сервере (подписанный webhook или GET платежа).

<!-- data-cobranca: id devolvido por POST /api/v1/cobrancas · data-voltar: opcional, só do seu site -->
<script src="https://ducripto.com/sdk/v1/checkout.js" data-cobranca="9b2f…" data-voltar="/obrigado" async></script>
<script>
  addEventListener('checkout:paga', (e) => mostrarObrigado(e.detail.cobranca));
</script>

Получение в USDC из любого токена

Передайте "aceita_conversao": true при создании платежа в USDC с указанной суммой. На странице оплаты плательщик выбирает SOL, USDT, JUP или BONK, видит, сколько потратит, и та же транзакция конвертирует средства и зачисляет точную сумму в USDC на ваш кошелёк. Webhook и запрос остаются прежними: учитывается поступивший USDC. В тестовом режиме недоступно.

curl -X POST https://ducripto.com/api/v1/cobrancas -H "Authorization: Bearer ib_…" -H "Content-Type: application/json" \
  -d '{"token":"USDC","valor":"49.90","externo_id":"1043","aceita_conversao":true}'
# → { "aceita_conversao": true, "url_pagamento": "https://ducripto.com/pagar/…", … }
# quem paga escolhe SOL, USDT, JUP ou BONK na página; você recebe 49.90 USDC exatos

Тестовая среда (sandbox)

Создайте ключ в режиме «Тест» (начинается с ib_test_). Он использует тот же API, но видит и создаёт только тестовые платежи, которые проходят в тестовой сети (modo: "teste" в ответе и в webhook) и никогда не попадают в вашу кассу. Чтобы протестировать без кошелька, сымитируйте оплату: POST /api/v1/cobrancas/{id}/simular-pagamento (для свободной суммы отправьте {"valor": "…"}). Webhook cobranca.paga приходит подписанным, как настоящий. Рабочий ключ не может имитировать оплату, и ключи не видят платежи друг друга.

# chave de teste (ib_test_…): mesma API, só cobranças de teste, rede de testes
curl -X POST https://ducripto.com/api/v1/cobrancas -H "Authorization: Bearer ib_test_XXXXXXXXXXXX_…" \
  -H "Content-Type: application/json" -d '{"token":"USDC","valor":"25.90","externo_id":"teste-1"}'
# → { "id": "9b2f…", "modo": "teste", "rede": "devnet", "estado": "pendente", … }

curl -X POST https://ducripto.com/api/v1/cobrancas/9b2f…/simular-pagamento -H "Authorization: Bearer ib_test_XXXXXXXXXXXX_…"
# → { "estado": "paga", "pagamento": { "assinatura": "simulado_…", … } } e o webhook cobranca.paga com "modo": "teste"

Ошибки и лимиты

Ошибки возвращаются в виде { erro: { codigo, mensagem } }. 401 — ключ недействителен или отозван · 403 — у ключа нет прав на операцию · 404 — платёж другого аккаунта или не существует · 409 — повтор externo_id или Idempotency-Key, использованный с другим телом · 422 — некорректные данные · 429 — более 120 запросов в минуту на ключ.

Контракт (OpenAPI)

Полная спецификация OpenAPI 3.1 (платежи, ошибки и webhook) доступна по адресу /api/v1/openapi.json — импортируйте её в Postman, Insomnia или генератор клиента. Она формируется из тех же схем, по которым тесты проверяют реальные ответы.

curl https://ducripto.com/api/v1/openapi.json