API tagihan

Autentikasi

Buat kunci di Tagih → API dan webhook (akun harus mengaktifkan verifikasi dua langkah). Kirim di header Authorization dan simpan hanya di server. Pilih aksesnya: “baca dan buat tagihan” (toko) atau “hanya baca” (rekonsiliasi, laporan). Kunci hanya-baca yang mencoba membuat tagihan menerima 403.

Authorization: Bearer ib_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Buat tagihan

token: USDC atau SOL. valor: desimal dengan titik, atau kosongkan untuk jumlah bebas. validade_horas: 1, 24, 72, 168, atau 720 (bawaan 24). externo_id: nomor pesanan di toko Anda, unik per rekening. Kirim Idempotency-Key (UUID) agar dapat mengulang dengan aman jika jaringan terputus.

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
}

Kueri

Nilai selalu dikembalikan sebagai teks dalam satuan bulat token (valor_unidades), tanpa kehilangan presisi. estado: pendente, paga, expirada, atau cancelada. Daftar dikembalikan per halaman: gunakan limite (1 hingga 100, bawaan 50) dan isi depois dengan nilai proximo untuk membaca halaman berikutnya; proximo null = akhir. Untuk dompet yang menyusun transaksi di server (Solana Pay "transaction request"), gunakan solana_pay_transacao; pada tagihan berjumlah bebas, tambahkan ?quantidade= ke URL sebelum di-encode.

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: tagihan dibayar

Menerima POST JSON dengan tipo cobranca.paga. Periksa tanda tangannya: HMAC-SHA256 dalam hex dari "timestamp.corpo" dengan secret Anda, dan tolak jika timestamp lebih dari 5 menit. Balas dengan 2xx; jika tidak, kami mengulang dengan jeda yang makin panjang. Gunakan evento_id untuk mengabaikan pengulangan.

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

Tombol pembayaran di situs Anda (SDK)

Satu baris skrip menampilkan tombol dengan merek Anda dan membuka checkout di tab baru; saat pembayaran terkonfirmasi, situs Anda menerima event checkout:paga. Event ini hanya untuk tampilan: serahkan pesanan setelah dikonfirmasi di server (webhook bertanda tangan atau GET tagihan).

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

Terima USDC dari token apa pun

Kirim "aceita_conversao": true saat membuat tagihan USDC dengan jumlah. Di halaman pembayaran, pembayar memilih SOL, USDT, JUP, atau BONK, melihat berapa yang akan dibelanjakan, dan transaksi yang sama mengonversi serta mengirim jumlah USDC yang tepat ke dompet Anda. Webhook dan kuerinya sama: yang dihitung adalah USDC yang diterima. Tidak berlaku dalam mode uji.

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

Lingkungan uji (sandbox)

Buat kunci dalam mode Uji (diawali ib_test_). Kunci ini memakai API yang sama, tetapi hanya melihat dan membuat tagihan uji, yang berada di jaringan uji (modo: "teste" dalam respons dan webhook) dan tidak pernah masuk ke kas Anda. Untuk menguji tanpa dompet, simulasikan pembayaran: POST /api/v1/cobrancas/{id}/simular-pagamento (untuk jumlah bebas, kirim {"valor": "…"}). Webhook cobranca.paga tiba bertanda tangan, sama seperti yang sungguhan. Kunci produksi tidak dapat menyimulasikan, dan satu kunci tidak dapat melihat tagihan kunci lainnya.

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

Error dan batasan

Error dikembalikan sebagai { erro: { codigo, mensagem } }. 401 kunci tidak valid atau dicabut · 403 kunci tidak memiliki cakupan untuk operasi tersebut · 404 tagihan milik rekening lain atau tidak ada · 409 externo_id berulang atau Idempotency-Key dipakai ulang dengan body berbeda · 422 data tidak valid · 429 lebih dari 120 panggilan per menit per kunci.

Kontrak (OpenAPI)

Spesifikasi OpenAPI 3.1 lengkap (tagihan, error, dan webhook) tersedia di /api/v1/openapi.json — impor ke Postman, Insomnia, atau generator klien. Spesifikasi ini dibuat dari skema yang sama yang diperiksa oleh pengujian terhadap respons sungguhan.

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