خطافات الويب

رد الاتصال URL

قم بتكوين رد اتصال الفريق URL في إعدادات تكامل المطور. يتحقق MakePay من إعدادات المنتج MakePay أولاً ثم إعدادات رد الاتصال المشتركة للمطورين، لذلك يمكن لإعدادات MakeSwap webhook الحالية تلقي أحداث الدفع MakePay أثناء طرح الإعداد الخاص بالمنتج.

عند حفظ رد اتصال MakePay URL، يقوم MakeCrypto بإنشاء سر webhook. قم بتخزينه في المدير السري للواجهة الخلفية لديك. يمكنك تجديده في أي وقت من نفس شاشة الإعدادات؛ بعد التجديد، قم بتحديث الواجهة الخلفية لديك قبل فرض التوقيعات بالسر الجديد.

سلوك التسليم

يرسل MakePay الدفع والاشتراك webhooks حسب طلبات POST بنص JSON. تتم إعادة محاولة عمليات التسليم الفاشلة حتى عشر مرات بفواصل زمنية مدتها خمس دقائق. تتوفر إعادة الإرسال اليدوي من سجلات طلبات MakeCrypto webhook.

الرؤوس

content-type: application/json
user-agent: MakePay-Webhooks/1.0
x-makepay-delivery-id: 9f1c6cf4-8514-4ee5-80fd-8e8fe2b5e313
x-makepay-delivery-group-id: 9f1c6cf4-8514-4ee5-80fd-8e8fe2b5e313
x-makepay-delivery-origin: event
x-makepay-event: status_changed
x-makepay-attempt: 1
x-makepay-signature: t=1776556800,v1=7d4b3f...

التحقق من التوقيعات

يقوم MakePay بتوقيع نص طلب JSON الخام الدقيق باستخدام HMAC-SHA256. حمولة التوقيع هي:

{timestamp}.{raw_request_body}

يحتوي رأس x-makepay-signature على الطابع الزمني لنظام Unix وملخص الإصدار:

t=1776556800,v1=<hex_hmac_sha256>

مثال للتحقق في Node.js:

import crypto from "node:crypto";

const WEBHOOK_SECRET = process.env.MAKEPAY_WEBHOOK_SECRET!;
const TOLERANCE_SECONDS = 300;

export function verifyMakePayWebhook(input: {
  rawBody: string;
  signatureHeader: string | null;
}) {
  if (!input.signatureHeader) {
    return false;
  }

  const parts = Object.fromEntries(
    input.signatureHeader.split(",").map((part) => {
      const [key, value] = part.trim().split("=");
      return [key, value];
    }),
  );

  const timestamp = Number(parts.t);
  const signature = parts.v1;

  if (!Number.isFinite(timestamp) || !signature) {
    return false;
  }

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > TOLERANCE_SECONDS) {
    return false;
  }

  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(`${timestamp}.${input.rawBody}`, "utf8")
    .digest("hex");
  const actualBuffer = Buffer.from(signature, "hex");
  const expectedBuffer = Buffer.from(expected, "hex");

  return (
    actualBuffer.length === expectedBuffer.length &&
    crypto.timingSafeEqual(actualBuffer, expectedBuffer)
  );
}

اقرأ النص الخام قبل تحليل JSON. إذا قام إطار العمل الخاص بك بتوزيع النص أولاً، فقم بتكوين مسار webhook لكشف بايتات الطلب الأولية والتحقق من تلك البايتات قبل الوثوق في الحمولة.

حمولة الدفع

{
  "deliveryId": "9f1c6cf4-8514-4ee5-80fd-8e8fe2b5e313",
  "type": "makepay.payment.status_changed",
  "createdAt": "2026-04-19T00:00:00.000Z",
  "event": {
    "type": "status_changed",
    "trigger": "payment_status_reconcile"
  },
  "paymentLink": {
    "id": "8d15bb78-d0f8-45ef-88d7-2a1f1f79644b",
    "uid": "01hzy4k6p4w9y2x7e2z7n8a2xm",
    "status": "active",
    "publicUrl": "https://makepay.io/payment/01hzy4k6p4w9y2x7e2z7n8a2xm",
    "expiresAt": "2026-04-19T12:00:00.000Z",
    "amount": "129.99",
    "currency": "USDT",
    "asset": "ETH.USDT-0xdac17f958d2ee523a2206206994597c13d831ec7",
    "label": "Website order #1042",
    "description": "Checkout for order #1042",
    "merchantOrderId": "order_1042",
    "clientEmail": "buyer@example.com",
    "clientId": null
  },
  "session": {
    "id": "5b55f0bb-0ac4-4f7c-a1d1-0d9af19c3bbd",
    "status": "complete",
    "previousStatus": "pending",
    "invoiceAsset": "USDT",
    "invoiceAmount": "129.99",
    "selectedSellAsset": "ETH",
    "requiredSellAmount": "0.04",
    "expectedBuyAmount": "129.99",
    "destinationAddress": "0xmerchant...",
    "depositAddress": "0xdeposit...",
    "channelId": "channel_123",
    "compositeChannelId": "ETH:channel_123",
    "sourceChain": "ETH",
    "expiresAt": "2026-04-19T00:30:00.000Z",
    "settlement": {},
    "errorMessage": null
  }
}

أنواع الأحداث

• status_changed لتغييرات حالة جلسة الدفع.
• settlement_updated عندما تتغير بيانات التسوية بعد تسوية الحالة.
• payment_request_expired، وquote_expired، وpayment_cancelled_by_payer لنتائج عدم الدفع النهائية.
• channel_created عندما يقبل الدافع عرض أسعار ويقوم MakePay بإنشاء قناة الإيداع.
• subscription_status_changed عندما ينتقل اشتراك MakePay بين active أو paused أو overdue أو cancelled.

quote_created وquote_refreshed هما حدثان داخليان للمخطط الزمني للدفع ولا يتم إرسالهما إلى رد الاتصال URLs.

حمولة الحالة Subscription

يرسل MakePay أيضًا رد اتصال عندما تتغير حالة الاشتراك. يقوم المجدول بوضع علامة على الاشتراك overdue عندما تكون أقدم دورة فوترة غير مدفوعة بعد 24 ساعة على الأقل من dueAt؛ بمجرد عدم تأخر أي دورة غير مدفوعة الأجر لأكثر من 24 ساعة، يقوم المجدول بنقل الاشتراك مرة أخرى إلى active. تستخدم تغييرات حالة بوابة التاجر والعملاء نفس رد الاتصال.

{
  "deliveryId": "78c35c42-61fb-4dd3-94b7-2a7df998bb6f",
  "type": "makepay.subscription.status_changed",
  "createdAt": "2026-04-20T00:00:00.000Z",
  "event": {
    "type": "subscription_status_changed",
    "trigger": "subscription_scheduler"
  },
  "subscription": {
    "id": "f6b76460-a437-4a81-a59f-8fcbb18c0f0f",
    "uid": "sub_premium_001",
    "status": "overdue",
    "previousStatus": "active",
    "customerEmail": "buyer@example.com",
    "label": "Premium plan",
    "description": "Monthly subscription",
    "amountUsd": "49.99",
    "settlementAsset": "ETH.USDT-0xdac17f958d2ee523a2206206994597c13d831ec7",
    "cadence": "monthly",
    "billingIntervalUnit": "month",
    "billingIntervalCount": 1,
    "startAt": "2026-04-18T00:00:00.000Z",
    "timezone": "Asia/Dubai",
    "metadata": {
      "clientId": "client_1042"
    },
    "createdAt": "2026-04-18T00:00:00.000Z",
    "updatedAt": "2026-04-20T00:00:00.000Z"
  },
  "cycle": {
    "id": "f303b3b3-26d8-42bc-8c10-91fa1445f507",
    "subscriptionId": "f6b76460-a437-4a81-a59f-8fcbb18c0f0f",
    "sequence": 0,
    "dueAt": "2026-04-18T00:00:00.000Z",
    "amountUsd": "49.99",
    "paymentLinkId": "8d15bb78-d0f8-45ef-88d7-2a1f1f79644b",
    "paymentLinkUid": "01hzy4k6p4w9y2x7e2z7n8a2xm",
    "paymentUrl": "https://makepay.io/payment/01hzy4k6p4w9y2x7e2z7n8a2xm",
    "status": "overdue"
  },
  "data": {
    "previousStatus": "active",
    "nextStatus": "overdue",
    "reason": "cycle_one_day_overdue"
  }
}

سجلات التسليم API

استخدم مسار طلب webhook لفحص عمليات التسليم وإعادة المحاولة.

GET /api/partner/v1/makepay/webhook-requests?limit=100

تشمل المرشحات الاختيارية paymentLinkUid، وdeliveryStatus، وsearch.