MakePay NPM SDK

ملخص

مكتبة MakePay npm SDK عبارة عن مكتبة JavaScript وTypeScript المكتوبة لتكاملات MakePay من جانب الخادم. فهو يلتف حول مصادقة مفتاح API، وعمليات رابط الدفع المستضافة، وإعدادات MakePay، والتحقق من webhook الموقع.

طَرد:

@makecrypto/makepay

تثبيت

npm install @makecrypto/makepay

pnpm add @makecrypto/makepay

يستهدف SDK الإصدار 18 من Node.js أو الأحدث ويستخدم تنفيذ fetch في وقت التشغيل.

المصادقة

قم بإنشاء مفتاح MakePay API من منطقة مطوري التاجر MakeCrypto وقم بتخزين سر المفتاح فقط على الخادم الخاص بك.

import { MakePayClient } from "@makecrypto/makepay";

const makepay = new MakePayClient({
  keyId: process.env.MAKEPAY_KEY_ID!,
  keySecret: process.env.MAKEPAY_KEY_SECRET!,
  // Optional: override only when MakePay gives you a custom checkout origin.
  checkoutBaseUrl: "https://makepay.io",
});

يرسل SDK رؤوس x-makecrypto-key-id وx-makecrypto-key-secret إلى شريك MakePay API.

إنشاء رابط الدفع

const response = await makepay.createPaymentLink({
  title: "Order #1042",
  description: "Checkout for order #1042",
  amount: "129.99",
  currency: "USDT",
  orderId: "order_1042",
  customerEmail: "buyer@example.com",
  returnUrl: "https://merchant.example/orders/1042",
  successUrl: "https://merchant.example/orders/1042/success",
  failureUrl: "https://merchant.example/orders/1042/pay",
  expirationTime: "12h",
});

console.log(response.paymentLink);

أرسل بريدًا إلكترونيًا لطلب الدفع MakePay أثناء الإنشاء:

await makepay.createPaymentLink(payload, {
  sendPaymentRequestEmail: true,
});

الخروج المضمنة

استخدم checkout URLs المستضاف لعمليات إعادة التوجيه، أو أدوات المساعدة المضمنة عندما تبقي الواجهة الأمامية للمتسوق على صفحة التاجر.

import {
  buildMakePayEmbeddedCheckoutUrl,
  buildMakePayHostedCheckoutUrl,
  mountMakePayCheckout,
  openMakePayCheckout,
} from "@makecrypto/makepay";

const paymentUid = response.paymentLink.uid;

const hostedUrl = buildMakePayHostedCheckoutUrl(paymentUid);
const embedUrl = buildMakePayEmbeddedCheckoutUrl(paymentUid, {
  parentOrigin: "https://merchant.example",
});

await openMakePayCheckout({
  paymentUid,
  onEvent(event) {
    if (event.type === "makepay.payment.redirect_requested") {
      window.location.assign(String(event.payload?.redirectUrl || hostedUrl));
    }
  },
});

mountMakePayCheckout({
  container: "#makepay-checkout",
  paymentUid,
});

بالنسبة لصفحات CMS الثابتة، تقوم buildMakePayEmbedButtonHtml(paymentUid) بإرجاع مقتطف زر يقوم بتحميل البرنامج النصي المشروط MakePay.

قراءة وتحديث الروابط

await makepay.listPaymentLinks();
await makepay.getPaymentLink("PAYMENT_LINK_UID");

await makepay.updatePaymentLink("PAYMENT_LINK_UID", {
  status: "paused",
});

await makepay.sendPaymentRequestEmail("PAYMENT_LINK_UID", "buyer@example.com");

إعدادات

await makepay.getSettings();

await makepay.updateSettings({
  callbackUrl: "https://merchant.example/webhooks/makepay",
});

التحقق من Webhook

اقرأ النص الخام الدقيق قبل تحليل JSON.

import { parseMakePayWebhook } from "@makecrypto/makepay";

export async function POST(request: Request) {
  const rawBody = await request.text();
  const event = parseMakePayWebhook(
    rawBody,
    request.headers.get("x-makepay-signature"),
    process.env.MAKEPAY_WEBHOOK_SECRET!,
  );

  if (event.event?.type === "status_changed") {
    // Update your local order.
  }

  return new Response("ok");
}

استخدم verifyMakePayWebhook عندما تحتاج فقط إلى نتيجة منطقية.

معالجة الأخطاء

مكالمات API ترمي MakePayError. يتضمن حالة HTTP ونص الاستجابة الذي تم فك تشفيره.

import { MakePayError } from "@makecrypto/makepay";

try {
  await makepay.getPaymentLink("PAYMENT_LINK_UID");
} catch (error) {
  if (error instanceof MakePayError) {
    console.error(error.status, error.responseBody);
  }
}

تخطيط المصدر

المصدر الأساسي موجود في apps/plugins/npm-sdk. تحتوي حزمة npm المنشورة على إعلانات ESM JavaScript وTypeScript المترجمة من dist.

ملاحظات الإصدار

تم نشر الحزمة باسم @makecrypto/makepay مع وصول عام. يجب أن يستخدم نشر الإصدار رمزًا مميزًا لأتمتة npm في مؤسسة makecrypto أو رمزًا مميزًا قادرًا على استخدام OTP عندما تكون المصادقة الثنائية مطلوبة.