API d’encaissement

Authentification

Créez la clé dans Encaisser → API et webhook (le compte doit avoir la vérification en deux étapes). Envoyez-la dans l’en-tête Authorization et gardez-la côté serveur uniquement. Choisissez l’accès : « lire et créer des paiements » (boutique) ou « lecture seule » (rapprochement, rapports). Une clé en lecture seule qui tente de créer reçoit 403.

Authorization: Bearer ib_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Créer une demande

token : USDC ou SOL. valor : décimal avec point, ou omis pour un montant libre. validade_horas : 1, 24, 72, 168 ou 720 (24 par défaut). externo_id : le numéro de commande de votre boutique, unique par compte. Envoyez Idempotency-Key (UUID) pour réessayer sans risque si le réseau coupe.

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
}

Consulter

Les montants sont toujours renvoyés en texte, en unités entières du jeton (valor_unidades), sans perte de précision. estado : pendente, paga, expirada ou cancelada. La liste est paginée : utilisez limite (1 à 100, 50 par défaut) et passez dans depois la valeur de proximo pour lire la page suivante ; proximo nul = fin. Pour les portefeuilles qui récupèrent la transaction sur le serveur (Solana Pay « transaction request »), utilisez solana_pay_transacao ; pour un montant libre, ajoutez ?quantidade= à l’URL avant de l’encoder.

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 : demande payée

Vous recevez un POST JSON avec tipo cobranca.paga. Vérifiez la signature : HMAC-SHA256 en hex de « timestamp.corps » avec votre secret, et refusez si le timestamp a plus de 5 minutes. Répondez 2xx ; sinon nous réessayons avec des délais croissants. Utilisez evento_id pour ignorer les doublons.

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

Bouton de paiement sur votre site (SDK)

Une ligne de script affiche le bouton à votre marque et ouvre le paiement dans un nouvel onglet ; une fois le paiement confirmé, votre site reçoit l’événement checkout:paga. L’événement sert à l’écran seulement : livrez la commande après confirmation côté serveur (webhook signé ou GET de la demande).

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

Recevoir des USDC depuis n’importe quel jeton

Envoyez "aceita_conversao": true en créant un paiement en USDC avec montant. Sur la page de paiement, le payeur choisit SOL, USDT, JUP ou BONK, voit combien il dépensera, et la même transaction convertit et livre le montant exact en USDC sur votre portefeuille. Le webhook et la consultation sont les mêmes : ce qui compte, c’est l’USDC arrivé. Indisponible en mode 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

Environnement de test (sandbox)

Créez une clé en mode Test (elle commence par ib_test_). Elle utilise la même API mais ne voit et ne crée que des paiements de test, sur le réseau de test (mode : "teste" dans la réponse et le webhook), qui n’entrent jamais dans votre solde. Pour tester sans portefeuille, simulez le paiement : POST /api/v1/cobrancas/{id}/simular-pagamento (montant libre : envoyez {"valor": "…"}). Le webhook cobranca.paga arrive signé, comme un vrai. La clé de production ne simule pas, et aucune clé ne voit les paiements de l’autre.

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

Erreurs et limites

Les erreurs arrivent sous la forme { erro: { codigo, mensagem } }. 401 clé invalide ou révoquée · 403 la clé n'a pas la portée de l'opération · 404 demande d’un autre compte ou inexistante · 409 externo_id répété ou Idempotency-Key réutilisée avec un autre corps · 422 données invalides · 429 plus de 120 appels par minute et par clé.

Contrat (OpenAPI)

La spécification OpenAPI 3.1 complète (paiements, erreurs et webhook) est sur /api/v1/openapi.json — importez-la dans Postman, Insomnia ou un générateur de client. Elle est générée à partir des mêmes schémas que les tests vérifient sur les réponses réelles.

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