Ödeme talebi API'si

Kimlik doğrulama

Anahtarı Ödeme iste → API ve webhook bölümünde oluşturun (hesapta iki adımlı doğrulama açık olmalıdır). Authorization başlığında gönderin ve yalnızca sunucuda saklayın. Erişimi seçin: “ödeme taleplerini oku ve oluştur” (mağaza) veya “yalnızca okuma” (mutabakat, raporlar). Oluşturmaya çalışan salt okunur bir anahtar 403 alır.

Authorization: Bearer ib_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Ödeme talebi oluştur

token: USDC veya SOL. valor: noktalı ondalık; açık tutar için boş bırakın. validade_horas: 1, 24, 72, 168 veya 720 (varsayılan 24). externo_id: mağazanızdaki sipariş numarası, hesap başına benzersiz. Ağ kesilirse güvenle tekrarlayabilmek için Idempotency-Key (UUID) gönderin.

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
}

Sorgula

Tutarlar her zaman tokenın tam birimleri cinsinden metin olarak döner (valor_unidades), hassasiyet kaybı olmadan. estado: pendente, paga, expirada veya cancelada. Liste sayfalar hâlinde gelir: limite (1 ile 100 arası, varsayılan 50) kullanın ve sonraki sayfayı okumak için depois parametresine proximo değerini verin; proximo null = son. İşlemi sunucuda hazırlayan cüzdanlar için (Solana Pay "transaction request") solana_pay_transacao kullanın; açık tutarlı ödeme talebinde kodlamadan önce URL'ye ?quantidade= ekleyin.

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: ödeme talebi ödendi

tipo cobranca.paga olan bir JSON POST alırsınız. İmzayı doğrulayın: gizli anahtarınızla "timestamp.corpo" üzerinden hex biçiminde HMAC-SHA256; timestamp 5 dakikadan eskiyse reddedin. 2xx ile yanıt verin; aksi hâlde artan aralıklarla yeniden deneriz. Tekrarları yok saymak için evento_id kullanın.

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

Sitenizde ödeme butonu (SDK)

Tek satırlık bir script markanızla butonu çizer ve ödeme sayfasını yeni sekmede açar; ödeme onaylandığında siteniz checkout:paga olayını alır. Olay yalnızca ekran içindir: siparişi sunucuda onayladıktan sonra teslim edin (imzalı webhook veya ödeme talebinin GET sorgusu).

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

Herhangi bir tokendan USDC olarak alın

Tutarlı bir USDC ödeme talebi oluştururken "aceita_conversao": true gönderin. Ödeme sayfasında ödeyen SOL, USDT, JUP veya BONK seçer, ne kadar harcayacağını görür ve aynı işlem dönüştürüp tam tutarı USDC olarak cüzdanınıza teslim eder. Webhook ve sorgu aynıdır: esas olan gelen USDC'dir. Test modunda geçerli değildir.

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

Test ortamı (sandbox)

Test modunda bir anahtar oluşturun (ib_test_ ile başlar). Aynı API'yi kullanır ancak yalnızca test ağında kalan test ödeme taleplerini görür ve oluşturur (yanıtta ve webhook'ta modo: "teste"); bunlar asla kasanıza girmez. Cüzdansız test için ödemeyi simüle edin: POST /api/v1/cobrancas/{id}/simular-pagamento (açık tutarda {"valor": "…"} gönderin). cobranca.paga webhook'u gerçeğiyle aynı şekilde imzalı gelir. Canlı anahtar simülasyon yapmaz ve bir anahtar diğerinin ödeme taleplerini göremez.

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

Hatalar ve limitler

Hatalar { erro: { codigo, mensagem } } biçiminde gelir. 401 geçersiz veya iptal edilmiş anahtar · 403 anahtarın bu işlem için kapsamı yok · 404 başka hesaba ait veya var olmayan ödeme talebi · 409 tekrarlanan externo_id veya başka gövdeyle yeniden kullanılan Idempotency-Key · 422 geçersiz veri · 429 anahtar başına dakikada 120 çağrının üzeri.

Sözleşme (OpenAPI)

Eksiksiz OpenAPI 3.1 spesifikasyonu (ödeme talepleri, hatalar ve webhook) /api/v1/openapi.json adresindedir — Postman, Insomnia veya bir istemci üreticisine aktarın. Testlerin gerçek yanıtlarla karşılaştırdığı şemaların aynısından üretilir.

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