MakePay NPM SDK

概述

MakePay npm SDK 是用于服务器端 MakePay 集成的类型化 JavaScript/TypeScript 库。它封装 API key 认证、托管支付链接操作、MakePay 设置和签名 Webhook 验证。

包名：

@makecrypto/makepay

安装

npm install @makecrypto/makepay

pnpm add @makecrypto/makepay

SDK 面向 Node.js 18 或更新版本，并使用运行时 fetch 实现。

身份验证

从 MakeCrypto 商户开发者区域创建 MakePay API 密钥，并只在服务器上保存 key secret。

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

const makepay = new MakePayClient({
  keyId: process.env.MAKEPAY_KEY_ID!,
  keySecret: process.env.MAKEPAY_KEY_SECRET!,
  checkoutBaseUrl: "https://makepay.io",
});

SDK 会向 MakePay 合作伙伴 API 发送 x-makecrypto-key-id 和 x-makecrypto-key-secret 请求头。

创建支付链接

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,
});

嵌入式结账

使用托管结账 URL 进行重定向；如果前端需要让购物者留在商户页面，可以使用嵌入辅助函数。

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 状态和解码后的响应体。

源码结构

规范源码位于 apps/plugins/npm-sdk。发布的 npm 包包含来自 dist 的编译后 ESM JavaScript 和 TypeScript 声明。

发布说明

包以 @makecrypto/makepay 名称公开发布。发布应使用 makecrypto 组织中的 npm 自动化 token，或在需要 2FA 时使用支持 OTP 的 token。