收款 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），并将 proximo 的值传入 depois 以读取下一页；proximo 为 null 表示结束。 对于从服务器获取交易的钱包（Solana Pay“transaction request”），请使用 solana_pay_transacao；金额不固定的收款请在编码前在 URL 后加上 ?quantidade=。

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：收款已支付

你会收到 tipo 为 cobranca.paga 的 JSON POST。请验证签名：用你的密钥对 "timestamp.body" 计算十六进制 HMAC-SHA256，时间戳超过 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 或查询收款）。

<!-- 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

创建带金额的 USDC 收款时发送 "aceita_conversao": true。在付款页面，付款人选择 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

测试环境（沙盒）

以“测试”模式创建密钥（以 ib_test_ 开头）。它使用同一套 API，但只能查看和创建测试收款，这些收款位于测试网络（响应和 webhook 中 modo 为 "teste"），永远不会计入您的余额。无需钱包即可测试：模拟付款 POST /api/v1/cobrancas/{id}/simular-pagamento（开放金额时发送 {"valor": "…"}）。cobranca.paga webhook 会像真实付款一样带签名送达。正式密钥不能模拟，两种密钥也互相看不到对方的收款。

# 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