مدفوعات بدون واجهة: دفع قائم على الإيداع باستدعاء واحد

إذا كنت تبني واجهة الدفع الخاصة بك — تطبيق محمول، منصة شريكة، متجر مخصص — فليست صفحة /pay/{id} المستضافة مناسبة دائمًا. لديك بالفعل تدفق محفظة خاص بك. وتعرف مسبقًا الشبكة والعملة التي سيدفع بها عميلك. ما تريده حقًا هو استدعاء API واحد يُعيد عنوان إيداع ومبلغًا دقيقًا يجب إرساله.

هذا ما تقدمه POST /api/payments/headless.

شكل الاستدعاء

استدعاء واحد داخل. استدعاء واحد خارج.

curl -X POST https://mutopay.com/api/payments/headless \
  -H "X-API-Key: ep_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "currency": "USD",
    "description": "طلب #1042",
    "external_id": "order_1042",

    "src_token_symbol": "USDT",
    "src_token_address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "src_chain_id": "137",
    "src_decimals": 6,
    "src_address": "0xCustomerWallet..."
  }'

{
  "id": "pay_abc123...",
  "status": "awaiting_payment",
  "route_type": "bridge",
  "protocol": "rubic",
  "deposit": {
    "address": "0xRubicDepositAddress...",
    "chain_id": "137",
    "chain_type": "evm",
    "token_symbol": "USDT",
    "token_address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "token_decimals": 6,
    "amount_raw": "25100000",
    "amount_human": "25.10",
    "payment_uri": "ethereum:0x...@137?value=25100000"
  },
  "bridge": {
    "name": "Across",
    "estimated_time_ms": 60000,
    "src_usd": "25.10",
    "bridge_fee_usd": "0.10"
  },
  "order_id": "rubic_exchange_id...",
  "expires_at": "2026-04-14T15:30:00Z"
}

يمتلك تطبيقك الآن كل ما يلزم: اطلب من العميل إرسال amount_raw بالضبط من العملة المصدر إلى address. اعرض رمز QR من payment_uri إن أردت. تابع استطلاع GET /api/payments/{id}/status حتى الحالة النهائية.

نوعان من المسارات، شكل واحد

• مباشر — نفس العملة ونفس الشبكة (يدفع العميل USDT على Polygon، وتُسوَّى أنت بـ USDT على Polygon). عنوان الإيداع هو محفظتك. بلا رسوم جسر ولا انتظار.
• إيداع مبادلة/جسر — مسار عابر للعملات أو للشبكات حيث يُرسل العميل معاملة واحدة إلى عنوان إدخال، وتصل عملة التسوية إلى محفظتك. دون توقيع أي طلب.

المسارات التي تتطلب من العميل توقيع طلب مُكتَّب أو تقديم معاملة مبادلة على السلسلة غير مدعومة في هذه النقطة — إن كان ذلك المسار الوحيد المتاح، فستتلقى استجابة 422. لهذه الحالات، استخدم صفحة /pay/{id} المستضافة أو الثلاثي الأدنى مستوى /quotes + /build-order + /submit-order.

ما يبقى عليك فعله

شيئان:

1. احصل على هاش المعاملة إن استطعت. لإيداعات المبادلة/الجسر، لا يلزمك فعل أي شيء — يلتقط المراقب الخلفي الإيداع ويضع علامة «مكتمل» على الدفعة. للمسارات المباشرة، يتحقق المراقب فقط عندما يتوفر هاش المعاملة، لذا استدعِ POST /api/payments/{id}/confirm مع { "tx_hash": "0x..." } بعد بث العميل للمعاملة. إن كانت واجهة محفظتك تعطيك الهاش (وأغلبها كذلك)، فهذا سطر واحد.

2. تابع استطلاع الحالة. GET /api/payments/{id}/status يُعيد الحالة الحالية بالإضافة إلى هاش المعاملة عند وصولها. الـ Webhook الذي كوّنته على قناتك يُطلق الأحداث ذاتها (payment.completed, payment.failed، إلخ) — استخدم ما يناسب هيكلك.

متى تستخدم أيّها

ما تبنيه	استخدم
تكامل WooCommerce / Shopify مع إعادة توجيه	POST /api/payments → /pay/{id}
واجهة دفع مخصصة تتحكم فيها بتدفق المحفظة	POST /api/payments/headless
تحتاج تقديم عدة مسارات مبادلة ليختار المستخدم	POST /api/payments + /quotes + /build-order

نقطة الـ headless أضيق عن قصد. تختار أفضل مسار قائم على الإيداع تلقائيًا، وتلتزم به، وتُعيد لك عنوان إيداع. إن احتجت تحكمًا إضافيًا — مفاضلة السرعة مقابل السعر، عدة خيارات مسارات، تدفقات الطلبات الموقَّعة — فالنقاط التفصيلية لا تزال متاحة.

المرجع الكامل في وثائق API. الأسئلة مرحَّب بها.