SDK MakePay NPM

Resumo

O npm SDK de MakePay é uma biblioteca digitada JavaScript e TypeScript para integrações do lado do servidor MakePay. Envolve autenticação com chave API, operações de link de pagamento hospedado, configuração MakePay e verificação de webhooks assinado.

Pacote:

@makecrypto/makepay

Instalação

npm install @makecrypto/makepay

pnpm add @makecrypto/makepay

O SDK é direcionado ao Node.js 18 ou superior e usa a implementação de tempo de execução fetch.

Autenticação

Crie uma chave API de MakePay na área de desenvolvedor comercial em MakeCrypto e salve o segredo apenas em seu servidor.

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

O SDK envia os cabeçalhos x-makecrypto-key-id e x-makecrypto-key-secret para o parceiro API de MakePay.

Criar link de pagamento

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

Envie um e-mail de solicitação de pagamento MakePay durante a criação:

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

Check-out incorporado

Use URLs checkout hospedados para redirecionamentos ou incorpore auxiliares quando seu front-end mantém o comprador na página do comerciante.

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

Para páginas CMS estáticas, buildMakePayEmbedButtonHtml(paymentUid) retorna um trecho de botão que carrega o script modal MakePay.

Ler e atualizar links

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

Configuração

await makepay.getSettings();

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

Verificação webhooks

Lê o corpo bruto exato antes de analisar o 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");
}

Use verifyMakePayWebhook quando precisar apenas de um resultado booleano.

Tratamento de erros

As chamadas API lançam MakePayError. Inclui o status HTTP e o corpo da resposta decodificado.

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

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

Estrutura de código

O código-fonte canônico reside em apps/plugins/npm-sdk. O pacote npm publicado contém declarações JavaScript ESM e TypeScript compiladas de dist.

Notas de versão

O pacote é publicado como @makecrypto/makepay com acesso público. A publicação de lançamento deve usar um token de automação npm na organização makecrypto ou um token compatível com OTP quando 2FA for necessário.