واجهة برمجة لمدفوعات العملات المشفرة مصممة للتسوية المباشرة

إنشاء فاتورة

طلب POST واحد. يُكتب المبلغ كما يكتبه الإنسان ويُحوَّل في الخادم حسب منازل الأصل العشرية، فلا تحوّل يدويًا إلى الوحدات الأساسية أبدًا.

curl -X POST https://api.unheld.io/api/v1/invoices \
  -H "Authorization: Bearer $UNHELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": "11155111",
    "assetType": "native",
    "amountDecimal": "0.05",
    "expiresInSeconds": 900,
    "metadata": { "orderId": "A-1043" }
  }'

الاستجابة

{
  "id": "e2b0…",
  "status": "CREATED",
  "receiveAddress": "0x…",
  "expectedAmount": "50000000000000000",
  "minConfirmations": 3,
  "expiresAt": "2026-08-10T14:15:00.000Z",
  "instructions": {
    "chainId": "11155111",
    "to": "0x…",
    "amount": "50000000000000000",
    "assetType": "native"
  }
}

يُشتق receiveAddress من محفظتك ويُقفل على هذه الفاتورة. وexpectedAmount بالوحدات الأساسية. أما minConfirmations فهو حد الشبكة نفسها، وليس إعدادًا اخترعناه.

المصادقة والصلاحيات

المفاتيح رموز bearer تُنشأ في لوحة التحكم وتُعرض مرة واحدة. ولكل مفتاح قائمة صلاحيات صريحة، ويُرفض الطلب إن لم يحمل المفتاح صلاحية ذلك المسار.

الصلاحيات المتاحة

• invoices:write
• invoices:read
• webhooks:write
• webhooks:read
• balances:read
• customers:write
• customers:read
• subscriptions:write
• subscriptions:read

امنح أضيق مجموعة تكفي. المفتاح الذي ينشئ الفواتير فقط لا يستطيع قراءة عملائك، ومفتاح القراءة المسرَّب لا يستطيع تحريك شيء — لأن لا شيء في هذه الواجهة يستطيع ذلك.

webhooks يمكنك التحقق منها

كل عملية تسليم موقَّعة. والتوقيع هو HMAC-SHA256 للطابع الزمني والجسم الخام موصولين بنقطة، باستخدام سر webhook الخاص بك، ويُرسل بصيغة سداسية عشرية.

التحقق من عملية تسليم

const signature = crypto
  .createHmac("sha256", webhookSecret)
  .update(`${req.headers["x-timestamp"]}.${rawBody}`)
  .digest("hex");

crypto.timingSafeEqual(
  Buffer.from(signature),
  Buffer.from(req.headers["x-signature"])
);

قارن البصمات بزمن ثابت، وارفض أي طابع زمني خارج نافذة التسامح لديك، وتعامل مع X-Request-Id كمفتاح عدم تكرار: فالمحاولات المعادة تستخدم القيمة نفسها، ووصول الحدث ذاته مرتين أمر طبيعي ويجب ألا يُعالَج مرتين.

أحداث الفاتورة

تمر الدفعة عبر حالات بدل أن تنتقل فجأة من غير مدفوعة إلى مدفوعة، وكل انتقال هو webhook. والدفع الناقص والدفع الزائد حدثان مستقلان، لا أخطاء.

أسئلة المطوّرين

جرى التحقق من الأمثلة على الواجهة المباشرة في 21 سبتمبر 2026.