वेबहुक

कॉलबैक URL

डेवलपर एकीकरण सेटिंग्स में टीम कॉलबैक URL कॉन्फ़िगर करें। MakePay पहले MakePay उत्पाद सेटिंग्स की जांच करता है और फिर साझा डेवलपर कॉलबैक सेटिंग्स की जांच करता है, इसलिए मौजूदा मेकस्वैप webhook सेटिंग्स MakePay भुगतान ईवेंट प्राप्त कर सकती हैं, जबकि उत्पाद-विशिष्ट सेटिंग को रोल आउट किया जा रहा है।

जब आप MakePay कॉलबैक URL सहेजते हैं, तो MakeCrypto एक webhook रहस्य उत्पन्न करता है। इसे अपने बैकएंड सीक्रेट मैनेजर में स्टोर करें। आप इसे किसी भी समय उसी सेटिंग स्क्रीन से पुन: उत्पन्न कर सकते हैं; पुनर्जनन के बाद, नए रहस्य के साथ हस्ताक्षर लागू करने से पहले अपने बैकएंड को अपडेट करें।

वितरण व्यवहार

MakePay POST अनुरोध के रूप में JSON बॉडी के साथ भुगतान और सदस्यता webhooks भेजता है। विफल डिलीवरी को पांच मिनट के अंतराल पर दस बार तक पुनः प्रयास किया जाता है। मैन्युअल पुनः भेजें 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, HMAC-SHA256 के साथ सटीक कच्चे JSON अनुरोध निकाय पर हस्ताक्षर करता है। हस्ताक्षर पेलोड है:

{timestamp}.{raw_request_body}

x-makepay-signature हेडर में यूनिक्स टाइमस्टैम्प और संस्करणित डाइजेस्ट शामिल है:

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 को चिह्नित करता है जब सबसे पुराना अवैतनिक बिलिंग चक्र dueAt से कम से कम 24 घंटे पहले होता है; एक बार जब कोई अवैतनिक चक्र 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 शामिल हैं।