API di incasso

Autenticazione

Crea la chiave in Incassa → API e webhook (il conto deve avere la verifica in due passaggi attiva). Inviala nell’header Authorization e conservala solo sul server. Scegli l’accesso: “leggere e creare richieste di pagamento” (negozio) o “solo lettura” (riconciliazione, report). Una chiave di sola lettura che tenta di creare riceve 403.

Authorization: Bearer ib_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Crea richiesta di pagamento

token: USDC o SOL. valor: decimale con il punto, oppure omettilo per un importo libero. validade_horas: 1, 24, 72, 168 o 720 (predefinito 24). externo_id: il numero d’ordine nel tuo negozio, univoco per conto. Invia Idempotency-Key (UUID) per poter ripetere in sicurezza se la connessione cade.

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
}

Consulta

Gli importi tornano sempre come testo in unità intere del token (valor_unidades), senza perdita di precisione. estado: pendente, paga, expirada o cancelada. L’elenco è paginato: usa limite (da 1 a 100, predefinito 50) e passa in depois il valore di proximo per leggere la pagina successiva; proximo nullo = fine. Per i wallet che costruiscono la transazione sul server (Solana Pay "transaction request"), usa solana_pay_transacao; nelle richieste con importo libero, aggiungi ?quantidade= all’URL prima di codificarlo.

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: pagamento ricevuto

Riceve un POST JSON con tipo cobranca.paga. Verifica la firma: HMAC-SHA256 in hex di "timestamp.corpo" con il tuo segreto, e rifiuta se il timestamp ha più di 5 minuti. Rispondi 2xx; altrimenti ripetiamo con attesa crescente. Usa evento_id per ignorare le ripetizioni.

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

Pulsante di pagamento sul tuo sito (SDK)

Una riga di script disegna il pulsante con il tuo marchio e apre il checkout in una nuova scheda; quando il pagamento è confermato, il tuo sito riceve l’evento checkout:paga. L’evento serve solo per l’interfaccia: consegna l’ordine dopo averlo confermato sul server (webhook firmato o GET della richiesta di pagamento).

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

Ricevi in USDC da qualsiasi token

Invia "aceita_conversao": true quando crei una richiesta di pagamento in USDC con importo. Nella pagina di pagamento, chi paga sceglie SOL, USDT, JUP o BONK, vede quanto spenderà, e la stessa transazione converte e consegna l’importo esatto in USDC nel tuo wallet. Il webhook e la consultazione sono gli stessi: conta l’USDC arrivato. Non vale in modalità test.

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

Ambiente di test (sandbox)

Crea una chiave in modalità Test (inizia con ib_test_). Usa la stessa API, ma vede e crea solo richieste di pagamento di test, che restano sulla rete di test (modo: "teste" nella risposta e nel webhook) e non entrano mai nella tua cassa. Per testare senza wallet, simula il pagamento: POST /api/v1/cobrancas/{id}/simular-pagamento (con importo libero, invia {"valor": "…"}). Il webhook cobranca.paga arriva firmato, come quello reale. La chiave di produzione non simula, e una chiave non vede le richieste di pagamento dell’altra.

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

Errori e limiti

Gli errori arrivano come { erro: { codigo, mensagem } }. 401 chiave non valida o revocata · 403 la chiave non ha l’ambito dell’operazione · 404 richiesta di pagamento di un altro conto o inesistente · 409 externo_id ripetuto o Idempotency-Key riutilizzata con un altro corpo · 422 dati non validi · 429 oltre 120 chiamate al minuto per chiave.

Contratto (OpenAPI)

La specifica OpenAPI 3.1 completa (richieste di pagamento, errori e il webhook) si trova in /api/v1/openapi.json — importala in Postman, Insomnia o in un generatore di client. Viene generata dagli stessi schemi che i test verificano sulle risposte reali.

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