SDK Libraries

NPM SDK

Install the official MakePay JavaScript and TypeScript SDK for payment links, settings, and webhook verification.

MakePay NPM SDK

Overview

@makecrypto/makepay is the official JavaScript and TypeScript SDK for MakePay server-side integrations. It wraps API-key authentication, payment and donation links, anonymous public links, customers, subscriptions, invoices, bookkeeping, POS terminals, product catalogs, Simple Shop, branded domains, operational APIs, and signed webhook verification.

Package:

@makecrypto/makepay

Public source repository:

https://github.com/makepay-io/makepay-npm-sdk

Installation

npm install @makecrypto/makepay

pnpm add @makecrypto/makepay

The SDK targets Node.js 18 or newer and uses the runtime fetch implementation.

Authentication

Create a MakePay API key from the MakeCrypto merchant developer area and store the key secret only on your server.

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

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

The SDK sends x-makecrypto-key-id and x-makecrypto-key-secret headers to the MakePay partner API. You can pass baseUrl for a non-production MakeCrypto API origin, and checkoutBaseUrl for a custom MakePay checkout origin.

Create Payment Link

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

Send a payment request email during creation:

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

Read and manage existing 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");

Donation Links

Donation links use the same settlement and checkout infrastructure as payment links, but they publish a public donation slug and allow flexible donor amounts.

const donation = await makepay.createDonationLink({
  title: "Spring campaign",
  description: "Support the 2026 spring fundraiser.",
  defaultAmountUsd: "25",
  minimumAmountUsd: "5",
  donationSlug: "spring-campaign",
});

console.log(donation.paymentLink.publicUrl);

await makepay.listDonationLinks();
await makepay.getDonationLink("DONATION_UID");
await makepay.updateDonationLink("DONATION_UID", { status: "paused" });

Anonymous Payment Links

Use anonymous links when a payment page should be created without a MakePay API key. Because there is no authenticated merchant account, the request must include settlement routing.

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

const response = await createAnonymousPaymentLink({
  amount: "25",
  settlement: {
    currency: "USDT",
    priorities: [
      {
        chain: "ETH",
        address: "0xYourSettlementWallet",
        asset: "ETH.USDT-0xdAC17F958D2ee523a2206206994597C13D831ec7",
      },
    ],
  },
  title: "Invoice #1042",
  customerEmail: "buyer@example.com",
  webhookUrl: "https://merchant.example/webhooks/makepay",
});

Anonymous link payloads support title, description, orderId, clientId, customerEmail, returnUrl, successUrl, failureUrl, metadata, branding, webhookUrl, and expirationTime values from 15 minutes to 72 hours.

Hosted And Embedded Checkout

Use hosted checkout URLs for full-page redirects, or the embed helpers when your frontend keeps the shopper on the merchant page.

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

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

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

Embedded checkout accepts viewType: "full" | "minimal". The default "full" view keeps the current hosted-payment style with the payment summary. Use "minimal" when the embed sits inside your own checkout page or modal and should show only the compact payment area.

Donation pages have hosted and embedded URL helpers too:

makepay.hostedDonationUrl("spring-campaign");
makepay.embeddedDonationUrl("spring-campaign", {
  parentOrigin: "https://merchant.example",
  viewType: "minimal",
});

For static CMS pages, buildMakePayEmbedButtonHtml(paymentUid) returns a button snippet that loads the MakePay modal script. Pass { viewType: "minimal" } to button, iframe, modal, or URL helpers when you want the compact embed view.

Customers

await makepay.upsertCustomer({
  email: "buyer@example.com",
  name: "Buyer Example",
  clientId: "crm_123",
  metadata: { plan: "pro" },
});

await makepay.listCustomers();

await makepay.createCustomerPortal("CUSTOMER_ID", {
  returnUrl: "https://merchant.example/account",
});

Subscriptions

await makepay.createSubscription({
  amountUsd: "29",
  customerEmail: "buyer@example.com",
  label: "Monthly plan",
  billingIntervalUnit: "month",
  billingIntervalCount: 1,
  sendPaymentRequestEmail: true,
});

await makepay.listSubscriptions();

Subscription invoice payment links are generated by the subscription API. Do not create subscription_invoice links directly through createPaymentLink.

POS Terminals

const terminal = await makepay.createPosTerminal({
  name: "Front counter",
  pin: "1234",
  allowedAssets: ["ETH.USDT-0xdAC17F958D2ee523a2206206994597C13D831ec7"],
  emailCollectionMode: "optional_after_deposit",
  catalogEnabled: true,
});

await makepay.listPosTerminals();
await makepay.getPosTerminal(String(terminal.terminal.uid));
await makepay.updatePosTerminal(String(terminal.terminal.uid), {
  name: "Front counter",
  pin: "5678",
  catalogEnabled: true,
});

Products

Products power POS catalogs and Simple Shop storefronts.

await makepay.createProduct({
  name: "Digital guide",
  productType: "digital",
  basePriceUsd: "19",
  shopSlug: "digital-guide",
  images: [{ url: "https://merchant.example/guide.png", alt: "Guide cover" }],
  variants: [{ name: "PDF", priceUsd: "19" }],
  taxRates: [{ name: "VAT", rateBps: 2000, isDefault: true }],
});

await makepay.listProducts();
await makepay.getProduct("PRODUCT_UID");
await makepay.updateProduct("PRODUCT_UID", {
  name: "Digital guide",
  status: "active",
});

Digital products can include downloads:

await makepay.createProductDownload("PRODUCT_UID", {
  fileName: "guide.pdf",
  contentType: "application/pdf",
  url: "https://merchant.example/downloads/guide.pdf",
});

await makepay.listProductDownloads("PRODUCT_UID");

Simple Shop

await makepay.updateShop({
  slug: "merchant-shop",
  displayCurrency: "USD",
  checkoutMode: "hosted",
  billingDetailsRequired: true,
  flatShippingFeeUsd: "5",
  freeShippingThresholdUsd: "100",
  branding: { accentColor: "#14b8a6" },
});

await makepay.getShop();
await makepay.updateShopBuilder({ blocks: [] });
await makepay.getShopBuilder();

Connect and verify a shop domain:

await makepay.updateShopDomain("shop.merchant.example");
await makepay.getShopDomain();
await makepay.refreshShopDomain();

Manage coupons and orders:

await makepay.createShopCoupon({
  code: "SPRING10",
  discountType: "percent",
  value: "10",
});

await makepay.listShopCoupons();
await makepay.updateShopCoupon("COUPON_UID", { status: "archived" });
await makepay.archiveShopCoupon("COUPON_UID");
await makepay.listShopOrders({ status: "paid", limit: 25 });

Invoices And Bookkeeping

Bookkeeping APIs manage merchant invoices, expenses, contacts, supporting documents, OCR, and reconciliation links. Contacts are shared across customer and vendor workflows: when the same email is used as a customer and vendor, the bookkeeping contact is marked as both.

const invoice = await makepay.createBookkeepingInvoice({
  title: "Invoice #1042",
  currency: "USD",
  issueDate: "2026-05-15",
  dueDate: "2026-05-30",
  counterparty: {
    name: "Buyer Example",
    email: "buyer@example.com",
    clientId: "crm_123",
  },
  lineItems: [
    {
      description: "Implementation services",
      quantity: "1",
      unitAmount: "500",
      taxAmount: "0",
    },
  ],
  metadata: { orderId: "order_1042" },
});

await makepay.createBookkeepingInvoicePaymentLink("INVOICE_UID", {
  sendPaymentRequestEmail: true,
});

await makepay.listBookkeepingInvoices();
await makepay.getBookkeepingInvoice("INVOICE_UID");
await makepay.updateBookkeepingInvoice("INVOICE_UID", { status: "open" });

Create and reconcile expenses manually or from wallet activity:

await makepay.createBookkeepingExpense({
  title: "Hosting",
  amount: "49",
  currency: "USD",
  incurredOn: "2026-05-15",
  category: "Infrastructure",
  counterparty: {
    name: "Vendor Example",
    email: "billing@vendor.example",
    type: "vendor",
  },
});

await makepay.createBookkeepingExpenseFromActivity({
  walletActivityEventKey: "CHAIN_EVENT_KEY",
  category: "Settlement",
});

await makepay.createBookkeepingReconciliation({
  invoiceId: "INVOICE_UID",
  paymentSessionId: "PAYMENT_SESSION_ID",
  linkType: "payment",
});

Wallet activity saves use the same behavior for outgoing chain transfers: MakeCrypto creates or updates a single paired expense, carries over private receipt or invoice files attached to the transfer, and keeps the reconciliation linked by wallet activity ID.

Document uploads use multipart form data through Blob or File.

await makepay.uploadBookkeepingDocument({
  file: new Blob([receiptBytes], { type: "application/pdf" }),
  fileName: "receipt.pdf",
  documentType: "receipt",
  expenseId: "EXPENSE_UID",
});

await makepay.uploadBookkeepingDocument({
  file: new Blob([invoiceBytes], { type: "application/pdf" }),
  fileName: "supplier-invoice.pdf",
  documentType: "invoice",
  walletActivityEventKey: "CHAIN_EVENT_KEY",
});

await makepay.listBookkeepingDocuments();
await makepay.getBookkeepingDocumentDownloadUrl("DOCUMENT_UID");
await makepay.runBookkeepingDocumentOcr("DOCUMENT_UID");
await makepay.getBookkeepingSummary();

Branding And Domains

Branding controls merchant display details, checkout theme colors, payment-link domains, and email-sending domains.

await makepay.updateBranding({
  brandName: "Merchant",
  businessDescription: "Digital products and services.",
  websiteUrl: "https://merchant.example",
  supportEmail: "support@merchant.example",
  brandingBrandColor: "#111827",
  brandingBrandTextColor: "#ffffff",
  brandingAccentColor: "#14b8a6",
  brandingAccentTextColor: "#ffffff",
  paymentLinkTheme: "system",
  paymentLinkDomain: "pay.merchant.example",
  emailSendingDomain: "mail.merchant.example",
});

const branding = await makepay.getBranding();
await makepay.refreshBrandingDomains("all");

Use refreshBrandingDomains("payment-link") or refreshBrandingDomains("email-sending") when you only need one domain check.

Operational APIs

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

await makepay.listDestinationAssets();
await makepay.listWebhookRequests({ limit: 25 });

listDestinationAssets is useful before configuring settlement overrides or anonymous settlement routes.

Webhook Verification

Read the exact raw body before parsing 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 when you only need a boolean result.

SDK Method Coverage

Area	Methods
Payment links	`createPaymentLink`, `listPaymentLinks`, `getPaymentLink`, `updatePaymentLink`, `sendPaymentRequestEmail`
Donations	`createDonationLink`, `listDonationLinks`, `getDonationLink`, `updateDonationLink`
Anonymous links	`createAnonymousPaymentLink`
Checkout	hosted, embedded, modal, button, iframe, and donation URL helpers
Customers	`listCustomers`, `upsertCustomer`, `createCustomerPortal`
Subscriptions	`listSubscriptions`, `createSubscription`
POS terminals	`listPosTerminals`, `createPosTerminal`, `getPosTerminal`, `updatePosTerminal`
Products	`listProducts`, `createProduct`, `getProduct`, `updateProduct`, `listProductDownloads`, `createProductDownload`
Simple Shop	`getShop`, `updateShop`, `getShopBuilder`, `updateShopBuilder`, `getShopDomain`, `updateShopDomain`, `refreshShopDomain`, coupon and order methods
Bookkeeping	summary, invoice, expense, document upload/OCR, and reconciliation methods
Branding	`getBranding`, `updateBranding`, `refreshBrandingDomains`
Operations	`getSettings`, `updateSettings`, `listDestinationAssets`, `listWebhookRequests`
Webhooks	`verifyMakePayWebhook`, `parseMakePayWebhook`

TypeScript, Data Models, And Response Models

@makecrypto/makepay is written in TypeScript and ships declaration files in the same npm package. You do not need a secondary SDK package or a separate @types package.

import type {
  MakePayBookkeepingInvoicePayload,
  MakePayBookkeepingSummaryResponse,
  MakePayPaymentLinkPayload,
  MakePayPaymentLinkResponse,
} from "@makecrypto/makepay";

Model conventions:

SDK payloads use camelCase. Some API routes also accept snake_case for compatibility, but new integrations should send camelCase.
Use strings for decimal money values when precision matters, for example "129.99" instead of 129.99.
Dates are ISO strings. Date-only fields, such as invoice issueDate, should use YYYY-MM-DD.
IDs are usually public uid values. Bookkeeping detail endpoints accept an internal UUID or public UID.
API methods throw MakePayError for non-2xx responses. Successful responses are typed envelopes with index signatures, so production can add fields without breaking TypeScript consumers.

Accepted Payload Models

Model	Used by	Required fields	Common optional fields
`MakePayPaymentLinkPayload`	`createPaymentLink`	`amount`	`title`, `description`, `currency`, `asset`, `orderId`, `customerEmail`, `clientId`, redirect URLs, `metadata`
`MakePayDonationLinkPayload`	`createDonationLink`	none	`defaultAmountUsd`, `minimumAmountUsd`, `donationSlug`, payment-link display and redirect fields
`MakePayAnonymousPaymentLinkPayload`	`createAnonymousPaymentLink`	`amount`, `settlement.currency`, `settlement.priorities`	`title`, `customerEmail`, `orderId`, `metadata`, `branding`, `webhookUrl`, checkout redirect URLs
`MakePayCustomerPayload`	`upsertCustomer`	one of `email`, `customerEmail`, `name`, `clientId`	`metadata`
`MakePaySubscriptionPayload`	`createSubscription`	plan amount/customer fields for your billing flow	`amountUsd`, `customerEmail`, `label`, `billingIntervalUnit`, `billingIntervalCount`, `startAt`, `sendPaymentRequestEmail`
`MakePayPosTerminalPayload`	`createPosTerminal`, `updatePosTerminal`	`name`	`pin`, `status`, `allowedAssets`, `emailCollectionMode`, `catalogEnabled`, `displaySettings`, `metadata`
`MakePayProductPayload`	`createProduct`, `updateProduct`	`name`	`description`, `sku`, `status`, `productType`, `basePriceUsd`, `shopSlug`, `images`, `variants`, `taxRates`, `metadata`
`MakePayShopPayload`	`updateShop`	none	`slug`, `status`, `displayCurrency`, `checkoutMode`, shipping fields, links, SEO, tracking, branding
`MakePayBrandingPayload`	`updateBranding`	none	brand name, support email, website URL, theme colors, `paymentLinkDomain`, `emailSendingDomain`
`MakePayBookkeepingInvoicePayload`	`createBookkeepingInvoice`, `updateBookkeepingInvoice`	none; blank invoices are allowed as drafts	`invoiceNumber`, `status`, `paymentStatus`, `currency`, `issueDate`, `dueDate`, `counterparty`, `lineItems`, `documentIds`
`MakePayBookkeepingExpensePayload`	`createBookkeepingExpense`, `createBookkeepingExpenseFromActivity`, `updateBookkeepingExpense`	none; amount defaults to zero if no activity is used	`amount`, `currency`, `category`, `incurredOn`, wallet activity IDs, `counterparty`, `metadata`
`MakePayBookkeepingDocumentUpload`	`uploadBookkeepingDocument`	`file`	`fileName`, `documentType`, `invoiceId`, `expenseId`
`MakePayBookkeepingReconciliationPayload`	`createBookkeepingReconciliation`	one target and one source	target: `invoiceId` or `expenseId`; source: payment, subscription cycle, or wallet activity; `amount`, `assetSymbol`, `metadata`
`Record<string, unknown>`	product downloads, shop builder, coupons, settings, customer portal	route-specific	these advanced surfaces stay open-ended while their server schemas evolve

Response Models By Function

Functions	Resolves to	Key fields
`createPaymentLink`, `getPaymentLink`, `updatePaymentLink`, `sendPaymentRequestEmail`, donation variants	`MakePayPaymentLinkResponse`	`ok`, `companyId`, `paymentLink`, `paymentRequestEmailSent`, `paymentRequestEmailError`
`listPaymentLinks`, `listDonationLinks`	`MakePayPaymentLinksResponse`	`companyId`, `paymentLinks`
`createAnonymousPaymentLink`	`MakePayPaymentLinkResponse`	`paymentLink`, plus public-link metadata returned by the API
`listCustomers`, `upsertCustomer`, `createCustomerPortal`	`MakePayCustomersResponse` or `MakePayCustomerResponse`	`customers`, `customer`, `portalUrl` or `url`
`listSubscriptions`, `createSubscription`	`MakePaySubscriptionsResponse` or `MakePaySubscriptionResponse`	`subscriptions`, `subscription`
`listPosTerminals`, `createPosTerminal`, `getPosTerminal`, `updatePosTerminal`	`MakePayPosTerminalsResponse` or `MakePayPosTerminalResponse`	`terminals`/`posTerminals`, `terminal`/`posTerminal`
`listProducts`, `createProduct`, `getProduct`, `updateProduct`, `listProductDownloads`, `createProductDownload`	product and download response types	`products`, `product`, `downloads`
`getShop`, `updateShop`, `getShopBuilder`, `updateShopBuilder`, `getShopDomain`, `updateShopDomain`, `refreshShopDomain`	shop, builder, and domain response types	`shop`, `blocks`, `builder`, `domain`, `status`, `verification`
`listShopCoupons`, `createShopCoupon`, `updateShopCoupon`, `archiveShopCoupon`, `listShopOrders`	coupon and order response types	`coupons`, `coupon`, `orders`
`getBranding`, `updateBranding`, `refreshBrandingDomains`, `getSettings`, `updateSettings`	branding/settings response types	`company`, `settings`, `ok`
`listDestinationAssets`, `listWebhookRequests`	operational response types	`assets`/`destinationAssets`, `webhookRequests`/`requests`
`getBookkeepingSummary`, invoice, expense, document, OCR, and reconciliation methods	bookkeeping response types	`summary`, `invoices`, `invoice`, `expenses`, `expense`, `documents`, `url`, `reconciliationLinks`, `stats`
`verifyMakePayWebhook`, `parseMakePayWebhook`	boolean or parsed event	`parseMakePayWebhook<T>()` returns your supplied event type after signature verification

Bookkeeping mutation methods return a fresh MakePayBookkeepingSummaryResponse, so dashboards can update invoice, expense, document, reconciliation, and stat views from a single response.

Error Handling

API calls throw MakePayError. It includes the HTTP status and decoded response body.

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

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

Release Notes

The package is published as @makecrypto/makepay with public access. Release publishing should use an npm automation token in the MakeCrypto organization or an OTP-capable token when 2FA is required.

The public repository at https://github.com/makepay-io/makepay-npm-sdk mirrors only the SDK package files so developers can inspect the source without the full MakeCrypto workspace.