Zahlungs-API

Authentifizierung

Schlüssel unter Kassieren → API und Webhook erstellen (das Konto braucht die Zwei-Schritt-Bestätigung). Im Header Authorization senden und nur serverseitig aufbewahren. Wählen Sie den Zugriff: „lesen und erstellen“ (Shop) oder „nur lesen“ (Abgleich, Berichte). Ein Nur-Lese-Schlüssel, der etwas erstellen will, erhält 403.

Authorization: Bearer ib_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Anforderung erstellen

token: USDC oder SOL. valor: Dezimalzahl mit Punkt, oder weglassen für freien Betrag. validade_horas: 1, 24, 72, 168 oder 720 (Standard 24). externo_id: Ihre Bestellnummer, eindeutig pro Konto. Idempotency-Key (UUID) senden, um bei Netzabbruch sicher zu wiederholen.

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
}

Abrufen

Beträge kommen immer als Text in ganzen Token-Einheiten (valor_unidades), ohne Präzisionsverlust. estado: pendente, paga, expirada oder cancelada. Die Liste ist seitenweise: limite (1 bis 100, Standard 50) setzen und den Wert von proximo in depois übergeben, um die nächste Seite zu lesen; proximo null = Ende. Für Wallets, die die Transaktion vom Server holen (Solana Pay „transaction request“), solana_pay_transacao verwenden; bei offenem Betrag ?quantidade= vor dem Kodieren an die URL anhängen.

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: Anforderung bezahlt

Sie erhalten einen JSON-POST mit tipo cobranca.paga. Signatur prüfen: HMAC-SHA256 (hex) von „timestamp.body“ mit Ihrem Geheimnis; ablehnen, wenn der Timestamp älter als 5 Minuten ist. Mit 2xx antworten, sonst wiederholen wir mit wachsender Wartezeit. evento_id nutzen, um Duplikate zu ignorieren.

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

Zahlungsbutton auf Ihrer Website (SDK)

Eine Script-Zeile zeigt den Button mit Ihrer Marke und öffnet den Checkout in einem neuen Tab; sobald die Zahlung bestätigt ist, erhält Ihre Seite das Ereignis checkout:paga. Das Ereignis ist nur für die Anzeige: liefern Sie erst nach Bestätigung auf dem Server aus (signierter Webhook oder GET der Anforderung).

<!-- 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 aus jedem Token erhalten

Senden Sie "aceita_conversao": true beim Erstellen einer USDC-Zahlung mit Betrag. Auf der Zahlungsseite wählt der Zahler SOL, USDT, JUP oder BONK, sieht, wie viel er ausgibt, und dieselbe Transaktion wandelt um und liefert genau den USDC-Betrag in Ihre Wallet. Webhook und Abfrage bleiben gleich: Es zählt das eingegangene USDC. Im Testmodus nicht verfügbar.

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

Testumgebung (Sandbox)

Erstellen Sie einen Schlüssel im Testmodus (beginnt mit ib_test_). Er nutzt dieselbe API, sieht und erstellt aber nur Testzahlungen im Testnetz (modo: "teste" in Antwort und Webhook), die nie in Ihr Guthaben eingehen. Zum Testen ohne Wallet die Zahlung simulieren: POST /api/v1/cobrancas/{id}/simular-pagamento (bei offenem Betrag {"valor": "…"} senden). Der Webhook cobranca.paga kommt signiert an, wie ein echter. Ein Live-Schlüssel kann nicht simulieren, und kein Schlüssel sieht die Zahlungen des anderen.

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

Fehler und Limits

Fehler kommen als { erro: { codigo, mensagem } }. 401 ungültiger oder widerrufener Schlüssel · 403 dem Schlüssel fehlt der Bereich der Operation · 404 Anforderung eines anderen Kontos oder nicht vorhanden · 409 wiederholte externo_id oder Idempotency-Key mit anderem Body · 422 ungültige Daten · 429 über 120 Aufrufe pro Minute und Schlüssel.

Vertrag (OpenAPI)

Die vollständige OpenAPI-3.1-Spezifikation (Zahlungsanforderungen, Fehler und Webhook) liegt unter /api/v1/openapi.json – importierbar in Postman, Insomnia oder einen Client-Generator. Sie wird aus denselben Schemas erzeugt, die die Tests gegen die echten Antworten prüfen.

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