Desarrolladores

API de cobros

Crea cobros en cripto desde el sistema de tu tienda, muestra el QR al cliente y recibe un aviso firmado cuando entre el pago. El dinero va directo a la billetera de la cuenta, sin intermediarios. Empieza por el entorno de pruebas, sin dinero real.

Autenticación

Crea la clave en Cobrar → API y webhook (la cuenta debe tener activada la verificación en dos pasos). Envíala en la cabecera Authorization y guárdala solo en el servidor. Elige el acceso: “leer y crear cobros” (tienda) o “solo lectura” (conciliación, informes). Una clave de solo lectura que intenta crear recibe 403.

Authorization: Bearer ib_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Crear cobro

token: USDC o SOL. valor: decimal con punto, u omítelo para monto abierto. validade_horas: 1, 24, 72, 168 o 720 (por defecto 24). externo_id: el número de pedido en tu tienda, único por cuenta. Envía Idempotency-Key (UUID) para reintentar con seguridad si se cae la red.

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
}

Consultar

Los montos vuelven siempre como texto en unidades enteras del token (valor_unidades), sin pérdida de precisión. estado: pendente, paga, expirada o cancelada. La lista viene paginada: usa limite (1 a 100, por defecto 50) y pasa en depois el valor de proximo para leer la página siguiente; proximo nulo = fin. Para billeteras que obtienen la transacción del servidor (Solana Pay "transaction request"), usa solana_pay_transacao; en cobros de valor abierto, añade ?quantidade= a la URL antes de codificarla.

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: cobro pagado

Recibes un POST JSON con tipo cobranca.paga. Verifica la firma: HMAC-SHA256 en hex de "timestamp.cuerpo" con tu secreto, y rechaza si el timestamp tiene más de 5 minutos. Responde 2xx; si no, reintentamos con espera creciente. Usa evento_id para ignorar repeticiones.

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);
  });
}

Botón de pago en tu sitio (SDK)

Una línea de script dibuja el botón con tu marca y abre el checkout en una pestaña nueva; cuando el pago se confirma, tu sitio recibe el evento checkout:paga. El evento es solo para la pantalla: entrega el pedido después de confirmarlo en el servidor (webhook firmado o GET del cobro).

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

Recibir USDC desde cualquier token

Envíe "aceita_conversao": true al crear un cobro en USDC con importe. En la página de pago, quien paga elige SOL, USDT, JUP o BONK, ve cuánto gastará, y la misma transacción convierte y entrega el importe exacto en USDC en su billetera. El webhook y la consulta son los mismos: cuenta el USDC que llegó. No vale en modo prueba.

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

Entorno de pruebas (sandbox)

Cree una clave en modo Prueba (empieza con ib_test_). Usa la misma API, pero solo ve y crea cobros de prueba, que quedan en la red de pruebas (modo: "teste" en la respuesta y en el webhook) y nunca entran en su saldo. Para probar sin billetera, simule el pago: POST /api/v1/cobrancas/{id}/simular-pagamento (con importe abierto, envíe {"valor": "…"}). El webhook cobranca.paga llega firmado, igual que el real. La clave de producción no simula, y ninguna clave ve los cobros de la otra.

# 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"

Errores y límites

Los errores vienen como { erro: { codigo, mensagem } }. 401 clave inválida o revocada · 403 la clave no tiene el alcance de la operación · 404 cobro de otra cuenta o inexistente · 409 externo_id repetido o Idempotency-Key reutilizada con otro cuerpo · 422 datos inválidos · 429 más de 120 llamadas por minuto por clave.

Contrato (OpenAPI)

La especificación OpenAPI 3.1 completa (cobros, errores y el webhook) está en /api/v1/openapi.json: impórtela en Postman, Insomnia o un generador de clientes. Se genera con los mismos esquemas que las pruebas comparan con las respuestas reales.

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