SDK MakePay НПМ

Обзор

NPM SDK для MakePay — это типизированная библиотека JavaScript и TypeScript для интеграции MakePay на стороне сервера. Он включает в себя аутентификацию по ключу API, операции с размещенными платежными ссылками, настройку MakePay и подписанную проверку webhooks.

Упаковка:

@makecrypto/makepay

Средство

npm install @makecrypto/makepay

pnpm add @makecrypto/makepay

SDK предназначен для Node.js 18 или более поздней версии и использует реализацию среды выполнения fetch.

Аутентификация

Создайте ключ API на основе MakePay из области разработчика merchant в 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 в API partner из MakePay.

Создать ссылку для оплаты

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-адреса checkout для перенаправления или встраивайте помощники, когда ваш интерфейс удерживает покупателя на странице merchant.

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

Проверка webhooks

Считывает точное необработанное тело перед анализом 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 содержит скомпилированные инструкции JavaScript ESM и TypeScript из dist.

Примечания к выпуску

Пакет опубликован как @makecrypto/makepay в публичном доступе. Публикация выпуска должна использовать токен автоматизации npm в организации makecrypto или токен, совместимый с OTP, если требуется 2FA.