معاينة: الدفع عبر CrypCash لم يُفتح بعد، وقد تتغير الباقات والمزايا قبل الإطلاق.

كل الأدلة

اربط CrypCash من شيفرتك الخاصة

للمطورين: أنشئ الفواتير بالواجهة البرمجية (REST)، وأرسل عميلك إلى صفحة الدفع أو ابنِ صفحتك، وحدّث الطلبات من إشعارات موقّعة.

قبل الإطلاق: تصف هذه الأدلة كيف سيجري التثبيت. لوحة CrypCash وإضافة WooCommerce وصفحة الدفع لم تُفتح بعد.

ما تحتاجه

  • مفتاحك السري محفوظًا على خادمك (انظر «قبل أن تبدأ»)
  • عنوان HTTPS على خادمك للإشعارات
  1. أنشئ فاتورة حين يُرسل الطلب

    اتصل بالواجهة من خادمك بمجموع الطلب، بـ USDT، أو بعملة متجرك مع currency (مثل INR أو EUR). يحوّله CrypCash بسعر السوق ويثبّت المبلغ طوال مهلة الفاتورة. وأرسل معرّف الطلب في Idempotency-Key: إن أُعيد الطلب رجعت إليك الفاتورة نفسها لا فاتورة ثانية.

    network هو TRON أو BSC، والعملة USDT. الحقول الاختيارية: orderId وdescription وcustomerEmail وmetadata (حتى 20 مفتاحًا) وsuccessUrl وcancelUrl وexpiresInMinutes (من 5 إلى 60، والافتراضي 15).

    إنشاء فاتورة
    curl -X POST https://api.crypcash.io/api/v1/invoices \
      -H "Authorization: Bearer $CRYPCASH_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: order-1042" \
      -d '{"amount":"4199","currency":"INR","network":"TRON","orderId":"1042","successUrl":"https://your-store.com/thanks"}'

    انقر الشيفرة أو المسها مرة واحدة فتُحدَّد كلها.

  2. أرسل عميلك ليدفع

    حوّله إلى checkoutUrl من الاستجابة. تعرض الصفحة المستضافة المبلغ والعنوان ورمز QR، وتتابع الدفع حتى يصير نهائيًّا. وللسعر بعملة أخرى يحفظ price سعرك الأصلي، وexchangeRate السعر الذي حُوّل به.

    تبني صفحتك بنفسك؟ اعرض payAmount لا amount: على عنوان TRON أو BNB Smart Chain الواحد يزيد حتى ⁦0.0999 USDT⁩، وهذا الفرق هو ما ينسب الدفع إلى الفاتورة.

    الاستجابة مختصرة
    201 Created
    {
      "id": "inv_…",
      "status": "PENDING",
      "network": "TRON",
      "currency": "USDT",
      "amount": "47.48",
      "payAmount": "47.4837",
      "price": { "amount": "4199", "currency": "INR" },
      "exchangeRate": { "currency": "INR", "asset": "USDT", "price": "88.4512", "source": "coingecko", "at": "2026-11-04T12:00:00.000Z" },
      "depositAddress": "T…",
      "paymentUri": null,
      "checkoutUrl": "https://crypcash.io/i/inv_…",
      "expiresAt": "2026-11-04T12:15:00.000Z"
    }
  3. أضف عنوان الإشعارات

    أضف عنوان HTTPS الذي يستقبل الإشعارات، ثم انسخ سرّ التوقيع الذي يعرضه CrypCash. احفظه على الخادم بجانب مفتاحك السري.

    لوحة CrypCash

    1. المتاجر
    2. متجرك
    3. الإشعارات
    4. إضافة عنوان
  4. تحقق من توقيع كل إشعار

    يحمل كل إشعار الترويسة CrypCash-Signature: t=<seconds>,v1=<hex>، وهي HMAC-SHA256 بسرّ التوقيع على t ثم نقطة ثم الجسم كما وصل. ارفض التوقيع الخاطئ، والتوقيع الأقدم من خمس دقائق.

    اقرأ الجسم كما وصل، قبل أن يمسّه محلل JSON. فالـ JSON الذي حُلّل ثم كُتب من جديد لا يطابق التوقيع.

    Node.js (Express)
    import express from "express";
    import { createHmac, timingSafeEqual } from "node:crypto";
    
    function verify(secret, rawBody, header = "") {
      const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
      if (!/^\d+$/.test(t ?? "") || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
      const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
      const given = Buffer.from(v1 ?? "", "hex");
      return given.length === expected.length && timingSafeEqual(given, expected);
    }
    
    const app = express();
    app.post("/api/crypcash/webhook", express.raw({ type: "application/json" }), (req, res) => {
      const raw = req.body.toString("utf8");
      if (!verify(process.env.CRYPCASH_WEBHOOK_SECRET, raw, req.get("CrypCash-Signature"))) return res.sendStatus(400);
      const event = JSON.parse(raw);
      if (event.type === "invoice.paid" || event.type === "invoice.overpaid") {
        markOrderPaid(event.data.invoice.orderId, event.id);
      }
      res.sendStatus(200);
    });
    PHP
    <?php
    function crypcash_verify(string $secret, string $rawBody, string $header): bool {
        $parts = [];
        foreach (explode(',', $header) as $pair) {
            [$key, $value] = array_pad(explode('=', $pair, 2), 2, '');
            $parts[$key] = $value;
        }
        $t = $parts['t'] ?? '';
        if (!ctype_digit($t) || abs(time() - (int) $t) > 300) {
            return false;
        }
        $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
        return hash_equals($expected, $parts['v1'] ?? '');
    }
    
    $raw = file_get_contents('php://input');
    if (!crypcash_verify((string) getenv('CRYPCASH_WEBHOOK_SECRET'), $raw, $_SERVER['HTTP_CRYPCASH_SIGNATURE'] ?? '')) {
        http_response_code(400);
        exit;
    }
    $event = json_decode($raw, true);
    if (in_array($event['type'], ['invoice.paid', 'invoice.overpaid'], true)) {
        mark_order_paid($event['data']['invoice']['orderId'], $event['id']);
    }
    http_response_code(200);
  5. حدّث الطلب بحسب الحدث

    اسم الحدث في type وفي الترويسة CrypCash-Event، والفاتورة في data.invoice ومعها orderId الخاص بك. أجب بأي حالة 2xx خلال 10 ثوانٍ، وإلا أعاد CrypCash المحاولة بمهل تطول كل مرة، من دقيقة إلى يوم.

    الحدث المكرر يحتفظ بمعرّفه id. احفظ المعرّفات التي عالجتها، وتجاهل المكرر.

    invoice.confirming
    رُئي الدفع ولم يصر نهائيًّا. اعرضه «قيد التأكيد»، ولا تشحن بعد.
    invoice.paid
    دُفع المبلغ كاملًا. علّم الطلب مدفوعًا.
    invoice.overpaid
    دُفع أكثر من المطلوب. علّمه مدفوعًا، وما وصل في data.invoice.receivedAmount.
    invoice.underpaid
    انتهى الوقت وقد وصل بعض المبلغ. قرّر مع عميلك.
    invoice.expired
    لم يصل شيء في الوقت. حرّر الطلب.
  6. جرّبه بدفعة حقيقية

    أنشئ فاتورة بـ ⁦1 USDT⁩ وادفعها من محفظة ثانية لك. يصل المال إلى عنوانك أنت، فلا تدفع إلا رسوم الشبكة. تحقق أن خادمك قبل التوقيع ونقل الطلب.

إن لم يعمل شيء

401 unauthorized

المفتاح ناقص أو خاطئ أو ملغى. أرسل المفتاح السري، الذي يبدأ بـ cc_sk_، في Authorization: Bearer.

402 volume_cap_exceeded

تتجاوز هذه الفاتورة حجم باقتك الشهري. يقول الخطأ كم بقي: رقِّ باقتك، أو انتظر الشهر التالي.

403 publishable_key_not_allowed

الفواتير ذات المبلغ تحتاج المفتاح السري من خادمك. المفتاح العام لا يحدد مبلغًا، لأن العميل يستطيع تغيير أي شيء في متصفحه.

422 wallet_not_configured

لا محفظة نشطة في المتجر لهذه الشبكة network. أضف واحدة من اللوحة.

422 asset_not_supported

العملة غير مقبولة على تلك الشبكة. أرسل USDT على TRON أو BNB Smart Chain.

422 asset_not_accepted

أوقف المتجر هذه العملة على محفظته في هذه الشبكة. فعّلها من اللوحة، أو أرسل العملة الأخرى.

422 currency_not_supported

لا سعر سوق عند CrypCash لهذه العملة currency. أرسل المبلغ بعملة الفاتورة، أو بعملة يحوّلها.

503 rate_unavailable

سعر هذه العملة قديم، فلا يحوّل به CrypCash. أعد المحاولة بعد المدة المكتوبة في Retry-After.

429 rate_limited

طلبات كثيرة في وقت واحد. انتظر عدد الثواني المكتوب في الترويسة Retry-After.

التوقيع لا يطابق أبدًا.

الأرجح أنك تتحقق من JSON حُلّل من قبل. استعمل الجسم كما وصل، وسرّ التوقيع (لا مفتاح الواجهة)، وt ثم نقطة ثم الجسم.

الدليل التاليمنصات أخرىالواجهة البرمجية، أو رابط دفع، أو طريقة دفع يدوية

Shopify وWooCommerce وWordPress وFramer وWebflow وv0 وLovable وBolt وTrustpilot علامات تجارية لأصحابها، ولا صلة لـ CrypCash بهم.