ওয়েবহুক

কলব্যাক URL

ডেভেলপার ইন্টিগ্রেশন সেটিংসে টিম কলব্যাক URL কনফিগার করুন৷ MakePay প্রথমে MakePay পণ্য সেটিংস এবং তারপর শেয়ার্ড ডেভেলপার কলব্যাক সেটিংস চেক করে, তাই বিদ্যমান MakeSwap webhook সেটিংস MakePay পেমেন্ট ইভেন্টগুলি গ্রহণ করতে পারে যখন পণ্য-নির্দিষ্ট সেটিং রোল আউট করা হচ্ছে৷

আপনি যখন একটি MakePay কলব্যাক URL সংরক্ষণ করেন, তখন MakeCrypto একটি webhook গোপনীয়তা তৈরি করে৷ এটি আপনার ব্যাকএন্ড সিক্রেট ম্যানেজারে সংরক্ষণ করুন। আপনি একই সেটিংস স্ক্রীন থেকে যেকোনো সময় এটি পুনরুত্পাদন করতে পারেন; পুনর্জন্মের পরে, নতুন গোপন সহ স্বাক্ষর প্রয়োগ করার আগে আপনার ব্যাকএন্ড আপডেট করুন।

ডেলিভারি আচরণ

MakePay একটি JSON বডি সহ POST অনুরোধ হিসাবে অর্থপ্রদান এবং সদস্যতা 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 হল অভ্যন্তরীণ পেমেন্ট টাইমলাইন ইভেন্ট এবং কলব্যাক URL-এ পাঠানো হয় না।

সাবস্ক্রিপশন স্ট্যাটাস পেলোড

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।