كل الأدلة
اربط CrypCash من شيفرتك الخاصة
للمطورين: أنشئ الفواتير بالواجهة البرمجية (REST)، وأرسل عميلك إلى صفحة الدفع أو ابنِ صفحتك، وحدّث الطلبات من إشعارات موقّعة.
قبل الإطلاق: تصف هذه الأدلة كيف سيجري التثبيت. لوحة CrypCash وإضافة WooCommerce وصفحة الدفع لم تُفتح بعد.
ما تحتاجه
- مفتاحك السري محفوظًا على خادمك (انظر «قبل أن تبدأ»)
- عنوان HTTPS على خادمك للإشعارات
أنشئ فاتورة حين يُرسل الطلب
اتصل بالواجهة من خادمك بمجموع الطلب، بـ 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"}'انقر الشيفرة أو المسها مرة واحدة فتُحدَّد كلها.
أرسل عميلك ليدفع
حوّله إلى
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" }أضف عنوان الإشعارات
أضف عنوان HTTPS الذي يستقبل الإشعارات، ثم انسخ سرّ التوقيع الذي يعرضه CrypCash. احفظه على الخادم بجانب مفتاحك السري.
لوحة CrypCash
- المتاجر
- متجرك
- الإشعارات
- إضافة عنوان
تحقق من توقيع كل إشعار
يحمل كل إشعار الترويسة
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);حدّث الطلب بحسب الحدث
اسم الحدث في
typeوفي الترويسةCrypCash-Event، والفاتورة فيdata.invoiceومعهاorderIdالخاص بك. أجب بأي حالة2xxخلال 10 ثوانٍ، وإلا أعاد CrypCash المحاولة بمهل تطول كل مرة، من دقيقة إلى يوم.الحدث المكرر يحتفظ بمعرّفه
id. احفظ المعرّفات التي عالجتها، وتجاهل المكرر.invoice.confirming- رُئي الدفع ولم يصر نهائيًّا. اعرضه «قيد التأكيد»، ولا تشحن بعد.
invoice.paid- دُفع المبلغ كاملًا. علّم الطلب مدفوعًا.
invoice.overpaid- دُفع أكثر من المطلوب. علّمه مدفوعًا، وما وصل في
data.invoice.receivedAmount. invoice.underpaid- انتهى الوقت وقد وصل بعض المبلغ. قرّر مع عميلك.
invoice.expired- لم يصل شيء في الوقت. حرّر الطلب.
جرّبه بدفعة حقيقية
أنشئ فاتورة بـ 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 بهم.