واجهة برمجة المدفوعات (API)

المصادقة

أنشئ المفتاح من الدفع ← API وwebhook (يجب أن يكون التحقق بخطوتين مفعّلًا في الحساب). أرسله في ترويسة Authorization واحتفظ به على الخادم فقط. اختر الصلاحية: «قراءة الطلبات وإنشاؤها» (المتجر) أو «قراءة فقط» (المطابقة، التقارير). المفتاح للقراءة فقط الذي يحاول الإنشاء يتلقى 403.

Authorization: Bearer ib_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

إنشاء مطالبة دفع

token: USDC أو SOL. valor: رقم عشري بنقطة، أو احذفه لمبلغ مفتوح. validade_horas: 1 أو 24 أو 72 أو 168 أو 720 (الافتراضي 24). externo_id: رقم الطلب في متجرك، فريد لكل حساب. أرسل Idempotency-Key (UUID) لتتمكن من إعادة المحاولة بأمان إذا انقطعت الشبكة.

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
}

الاستعلام

تُعاد المبالغ دائمًا كسلاسل نصية بوحدات الرمز الصحيحة (valor_unidades)، دون فقدان للدقة. estado: pendente أو paga أو expirada أو cancelada. تُعاد القائمة على صفحات: استخدم limite (من 1 إلى 100، والافتراضي 50) ومرّر قيمة proximo في depois لقراءة الصفحة التالية؛ وإذا كانت proximo فارغة (null) فهذه النهاية. للمحافظ التي تجلب المعاملة من الخادم (Solana Pay "transaction request")، استخدم solana_pay_transacao؛ وفي المطالبات ذات المبلغ المفتوح، أضف ?quantidade= إلى عنوان URL قبل ترميزه.

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: تم دفع المطالبة

تستلم طلب POST بصيغة JSON يحمل tipo cobranca.paga. تحقق من التوقيع: HMAC-SHA256 بصيغة hex لـ "timestamp.body" باستخدام سرّك، وارفض الطلب إذا كان الطابع الزمني أقدم من 5 دقائق. أجب بـ 2xx؛ وإلا فسنعيد المحاولة بفواصل زمنية متزايدة. استخدم evento_id لتجاهل الطلبات المكررة.

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

زر الدفع في موقعك (SDK)

سطر سكربت واحد يعرض الزر بعلامتك التجارية ويفتح صفحة الدفع في علامة تبويب جديدة؛ وعند تأكيد الدفع يتلقى موقعك الحدث checkout:paga. الحدث للعرض فقط: سلّم الطلب بعد التأكيد على الخادم (webhook موقّع أو GET لطلب الدفع).

<!-- 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 من أي رمز

أرسل "aceita_conversao": true عند إنشاء طلب دفع بـ USDC بمبلغ محدد. في صفحة الدفع يختار الدافع SOL أو USDT أو JUP أو BONK، ويرى ما سيدفعه، وتقوم المعاملة نفسها بالتحويل وتسليم المبلغ الدقيق بـ USDC إلى محفظتك. الـ webhook والاستعلام كما هما: العبرة بـ USDC الذي وصل. غير متاح في الوضع التجريبي.

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

بيئة الاختبار (sandbox)

أنشئ مفتاحًا في الوضع التجريبي (يبدأ بـ ib_test_). يستخدم الواجهة نفسها لكنه لا يرى ولا ينشئ إلا طلبات دفع تجريبية على شبكة الاختبار (modo: "teste" في الرد وفي الـ webhook)، ولا تدخل أبدًا في رصيدك. للاختبار دون محفظة، حاكِ الدفع: POST /api/v1/cobrancas/{id}/simular-pagamento (للمبلغ المفتوح أرسل {"valor": "…"}). يصل webhook ‏cobranca.paga موقّعًا مثل الحقيقي. مفتاح الإنتاج لا يحاكي، ولا يرى أي مفتاح طلبات الآخر.

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

الأخطاء والحدود

تأتي الأخطاء بالشكل { erro: { codigo, mensagem } }. 401 مفتاح غير صالح أو ملغى · 403 المفتاح لا يملك نطاق العملية · 404 مطالبة تخص حسابًا آخر أو غير موجودة · 409 تكرار externo_id أو إعادة استخدام Idempotency-Key بمحتوى مختلف · 422 بيانات غير صالحة · 429 تجاوز 120 استدعاءً في الدقيقة لكل مفتاح.

العقد (OpenAPI)

مواصفة OpenAPI 3.1 الكاملة (الطلبات والأخطاء وwebhook) موجودة في ‎/api/v1/openapi.json — استوردها في Postman أو Insomnia أو مولّد عملاء. تُولَّد من المخططات نفسها التي تتحقق منها الاختبارات مقابل الاستجابات الفعلية.

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