Official JavaScript and TypeScript SDK for MakePay server-side integrations. Use it to create crypto payment links, donation pages, invoices, bookkeeping records, subscriptions, POS terminals, products, Simple Shop storefronts, customer portals, branded domains, and signed webhook handlers.
Public source: https://github.com/makepay-io/makepay-npm-sdk
npm install @makecrypto/makepaypnpm add @makecrypto/makepayThe SDK targets Node.js 18 or newer and uses the runtime fetch
implementation.
Create a MakePay API key in MakeCrypto and keep the secret on your server only.
import{MakePayClient}from"@makecrypto/makepay";constmakepay=newMakePayClient({keyId: process.env.MAKEPAY_KEY_ID!,keySecret: process.env.MAKEPAY_KEY_SECRET!,});The client sends x-makecrypto-key-id and x-makecrypto-key-secret headers to
the MakePay partner API.
Custom API and checkout base URLs must be origin-only HTTPS URLs. For local
tests, HTTP is accepted only with the exact hosts localhost, 127.0.0.1, or
[::1] (an explicit port is allowed). Userinfo, paths, query strings,
fragments, lookalike hostnames, and alternate numeric IP encodings are rejected.
The same policy applies to anonymous requests and every hosted, embedded,
modal-script, button, and iframe URL helper. DPoP proof target URLs use the same
HTTPS-or-exact-loopback transport rule while retaining their required path.
Embedded-checkout parentOrigin values are independently validated as strict
merchant origins before being serialized or used as the browser default.
Native integrations can instead supply OAuth credentials asynchronously. The host application remains responsible for encrypting tokens and the DPoP private key, serializing refreshes, and atomically persisting rotated refresh tokens.
import{MakePayClient,createMakePayDpopProof,typeMakePayAuthProvider,}from"@makecrypto/makepay";constauthProvider: MakePayAuthProvider={asyncgetAuthorization({ method, url }){constcredentials=awaittokenStore.load();return{accessToken: credentials.accessToken,tokenType: "DPoP",dpopProof: createMakePayDpopProof({accessToken: credentials.accessToken,
method,privateKey: credentials.dpopPrivateKeyPem,
url,}),};},asyncrefreshAuthorization(){// Refresh once under your application's lock and persist both rotated// tokens before this promise resolves.awaittokenStore.refresh();},};constmakepay=newMakePayClient({ authProvider });On a 401, the SDK invokes refreshAuthorization at most once and rebuilds
authorization (including a fresh DPoP proof) before one retry. It never owns or
persists OAuth tokens. generateMakePayDpopKeyPair,
calculateMakePayDpopJwkThumbprint, and createMakePayDpopProof are available
for native authorization-code integrations.
constresponse=awaitmakepay.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",},{// Reuse this value while reconciling an ambiguous network outcome.idempotencyKey: "order_1042:payment-link:v1",},);console.log(response.paymentLink);createPaymentLink, updatePaymentLink, and the current webhook-subscription
mutations accept an idempotencyKey. Reuse the same key only for an identical
mutation; MakePay rejects reuse with a different method, path, or body.
Read, update, and email existing links:
awaitmakepay.listPaymentLinks();awaitmakepay.getPaymentLink("PAYMENT_LINK_UID");awaitmakepay.updatePaymentLink("PAYMENT_LINK_UID",{status: "paused"});awaitmakepay.updatePaymentLink("PAYMENT_LINK_UID",{metadata: {medusaOrderId: "order_01J...",medusaOrderDisplayId: "1042",medusaAdminUrl: "https://merchant.example/app/orders/order_01J...",medusaInstallationId: "installation_01J...",},});awaitmakepay.sendPaymentRequestEmail("PAYMENT_LINK_UID","buyer@example.com");Donation pages are flexible-amount payment links with a public donation slug.
constdonation=awaitmakepay.createDonationLink({title: "Spring campaign",description: "Support the 2026 spring fundraiser.",defaultAmountUsd: "25",minimumAmountUsd: "5",donationSlug: "spring-campaign",});console.log(donation.paymentLink.publicUrl);awaitmakepay.listDonationLinks();awaitmakepay.getDonationLink("DONATION_UID");awaitmakepay.updateDonationLink("DONATION_UID",{status: "paused"});Anonymous links do not use a MakePay API key. They require an explicit settlement route because MakePay cannot read merchant wallet settings.
import{createAnonymousPaymentLink}from"@makecrypto/makepay";constresponse=awaitcreateAnonymousPaymentLink({amount: "25",settlement: {currency: "USDT",priorities: [{chain: "ETH",address: "0xYourSettlementWallet",asset: "ETH.USDT-0xdAC17F958D2ee523a2206206994597C13D831ec7",},],},title: "Invoice #1042",webhookUrl: "https://merchant.example/webhooks/makepay",});Use hosted checkout for redirects, or the embed helpers when your frontend keeps the shopper on the merchant site.
import{buildMakePayEmbeddedCheckoutUrl,buildMakePayHostedCheckoutUrl,mountMakePayCheckout,openMakePayCheckout,}from"@makecrypto/makepay";constpaymentUid=response.paymentLink.uid;consthostedUrl=buildMakePayHostedCheckoutUrl(paymentUid);constembedUrl=buildMakePayEmbeddedCheckoutUrl(paymentUid,{parentOrigin: "https://merchant.example",viewType: "minimal",});awaitopenMakePayCheckout({
paymentUid,viewType: "minimal",onEvent(event){if(event.type==="makepay.payment.redirect_requested"){window.location.assign(String(event.payload?.redirectUrl||hostedUrl));}},});constmounted=mountMakePayCheckout({container: "#makepay-checkout",
paymentUid,viewType: "minimal",});Embedded checkout supports viewType: "full" | "minimal". The default
"full" view matches the hosted payment page layout. Use "minimal" when the
checkout is already inside your own page or modal and should show only the
compact payment form. The mounted helper accepts checkout events only when both
the configured MakePay origin and the mounted iframe window match.
Donation pages also have URL helpers:
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, and buildMakePayIframeHtml
returns an iframe snippet. Pass { viewType: "minimal" } to either helper to
request the compact embed.
awaitmakepay.upsertCustomer({email: "buyer@example.com",name: "Buyer Example",clientId: "crm_123",});awaitmakepay.createCustomerPortal("CUSTOMER_ID",{returnUrl: "https://merchant.example/account",});awaitmakepay.createSubscription({amountUsd: "29",customerEmail: "buyer@example.com",label: "Monthly plan",billingIntervalUnit: "month",billingIntervalCount: 1,});constterminal=awaitmakepay.createPosTerminal({name: "Front counter",pin: "1234",allowedAssets: ["ETH.USDT-0xdAC17F958D2ee523a2206206994597C13D831ec7"],emailCollectionMode: "optional_after_deposit",catalogEnabled: true,});awaitmakepay.listPosTerminals();awaitmakepay.getPosTerminal(String(terminal.terminal.uid));awaitmakepay.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"}],});awaitmakepay.createProductDownload("PRODUCT_UID",{fileName: "guide.pdf",contentType: "application/pdf",url: "https://merchant.example/downloads/guide.pdf",});awaitmakepay.updateShop({slug: "merchant-shop",displayCurrency: "USD",checkoutMode: "hosted",branding: {accentColor: "#14b8a6"},});awaitmakepay.updateShopDomain("shop.merchant.example");awaitmakepay.refreshShopDomain();awaitmakepay.createShopCoupon({code: "SPRING10",discountType: "percent",value: "10",});awaitmakepay.listShopOrders({status: "paid",limit: 25});Bookkeeping APIs manage merchant invoices, expenses, supporting documents, OCR, and reconciliation links.
constcreated=awaitmakepay.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"},});awaitmakepay.createBookkeepingInvoicePaymentLink("INVOICE_UID",{sendPaymentRequestEmail: true,});awaitmakepay.listBookkeepingInvoices();awaitmakepay.getBookkeepingInvoice("INVOICE_UID");awaitmakepay.updateBookkeepingInvoice("INVOICE_UID",{status: "open"});Expenses can be created manually or from wallet activity, then linked back to payments, transfers, invoices, or uploaded receipts.
awaitmakepay.createBookkeepingExpense({title: "Hosting",amount: "49",currency: "USD",incurredOn: "2026-05-15",category: "Infrastructure",counterparty: {name: "Vendor Example",type: "vendor"},});awaitmakepay.createBookkeepingExpenseFromActivity({walletActivityEventKey: "CHAIN_EVENT_KEY",category: "Settlement",});awaitmakepay.createBookkeepingReconciliation({invoiceId: "INVOICE_UID",paymentSessionId: "PAYMENT_SESSION_ID",linkType: "payment",});Document uploads use multipart form data through Blob or File.
awaitmakepay.uploadBookkeepingDocument({file: newBlob([receiptBytes],{type: "application/pdf"}),fileName: "receipt.pdf",documentType: "receipt",expenseId: "EXPENSE_UID",});awaitmakepay.listBookkeepingDocuments();awaitmakepay.getBookkeepingDocumentDownloadUrl("DOCUMENT_UID");awaitmakepay.runBookkeepingDocumentOcr("DOCUMENT_UID");awaitmakepay.getBookkeepingSummary();awaitmakepay.updateBranding({brandName: "Merchant",supportEmail: "support@merchant.example",brandingBrandColor: "#111827",brandingAccentColor: "#14b8a6",paymentLinkTheme: "system",paymentLinkDomain: "pay.merchant.example",emailSendingDomain: "mail.merchant.example",});awaitmakepay.refreshBrandingDomains("all");awaitmakepay.getSettings();awaitmakepay.updateSettings({callbackUrl: "https://merchant.example/webhooks/makepay",});awaitmakepay.listDestinationAssets();awaitmakepay.listWebhookRequests({limit: 25});OAuth integrations should use a grant-scoped webhook subscription rather than changing a company-global callback URL. The signing secret is returned only on creation or explicit rotation, so persist it immediately. PUT and DELETE require an idempotency key.
constcreated=awaitmakepay.upsertCurrentWebhookSubscription({url: "https://merchant.example/webhooks/makepay",events: ["makepay.payment.status_changed"],},{idempotencyKey: "installation_123:webhook:v1"},);awaitmakepay.getCurrentWebhookSubscription();awaitmakepay.deleteCurrentWebhookSubscription({idempotencyKey: "installation_123:webhook-delete:v1",});Read the exact raw body before parsing JSON.
import{parseMakePayWebhook}from"@makecrypto/makepay";exportasyncfunctionPOST(request: Request){constrawBody=awaitrequest.text();constevent=parseMakePayWebhook(rawBody,request.headers.get("x-makepay-signature"),process.env.MAKEPAY_WEBHOOK_SECRET!,);if(event.event?.type==="status_changed"){// Update your local order status.}returnnewResponse("ok");}Use verifyMakePayWebhook when you only need a boolean result. Webhook
timestamps use a 300-second freshness window by default. A custom
toleranceSeconds must be finite and greater than zero; zero, negative, NaN,
and infinite values fail verification.
| Area | SDK methods |
|---|---|
| Payment links | createPaymentLink, listPaymentLinks, getPaymentLink, updatePaymentLink, sendPaymentRequestEmail |
| Donations | createDonationLink, listDonationLinks, getDonationLink, updateDonationLink |
| Anonymous links | createAnonymousPaymentLink |
| Checkout | hosted, embedded, modal, button, and iframe 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, coupons, orders |
| Bookkeeping | summary, invoice, expense, document upload/OCR, and reconciliation methods |
| Branding | getBranding, updateBranding, refreshBrandingDomains |
| Operations | getSettings, updateSettings, listDestinationAssets, listWebhookRequests, current webhook subscription CRUD |
| Webhooks | verifyMakePayWebhook, parseMakePayWebhook |
@makecrypto/makepay is written in TypeScript and ships declaration files in
the same npm package. You do not need @types/makecrypto__makepay or a
secondary SDK package.
importtype{MakePayAnonymousPaymentLinkResponse,MakePayBookkeepingInvoicePayload,MakePayBookkeepingSummaryResponse,MakePayAuthProvider,MakePayDonationLinksResponse,MakePayPaymentLinkPayload,MakePayPaymentLinkResponse,MakePayPaymentRequestEmailResponse,MakePayWebhookSubscriptionResponse,}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 of129.99. - Dates are ISO strings. Date-only fields, such as invoice
issueDate, should useYYYY-MM-DD. - IDs are usually public
uidvalues. Bookkeeping detail endpoints accept an internal UUID or public UID. - Authenticated partner-v1 payment links retain the original values under
paymentLink.payloadand also expose normalizedamount,fiatCurrency,metadata, correlation fields, latest session, and timeline fields directly onpaymentLink. - API methods throw
MakePayErrorfor non-2xx responses. Successful responses are typed envelopes with index signatures, so production can add fields without breaking TypeScript consumers.
| Model | Used by | Required fields | Common optional fields |
|---|---|---|---|
MakePayPaymentLinkPayload | createPaymentLink | amount | title, description, currency, asset, orderId, customerEmail, clientId, returnUrl, successUrl, metadata |
MakePayPaymentLinkUpdate | updatePaymentLink | at least one update field | status/expiry controls or allowlisted Medusa order-correlation 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, billingDetailsRequired, 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, walletActivityEventId, walletActivityEventKey, counterparty, metadata |
MakePayBookkeepingDocumentUpload | uploadBookkeepingDocument | file | fileName, documentType, invoiceId, expenseId |
MakePayBookkeepingReconciliationPayload | createBookkeepingReconciliation | one target and one source | target: invoiceId or expenseId; source: payment link/session, subscription cycle, or wallet activity; amount, assetSymbol |
Record<string, unknown> | product downloads, shop builder, coupons, settings, customer portal | route-specific | these advanced surfaces stay open-ended while their server schemas evolve |
| Functions | Resolves to | Key fields |
|---|---|---|
createPaymentLink, getPaymentLink, updatePaymentLink, donation create/detail/update | MakePayPaymentLinkResponse | required companyId; normalized paymentLink plus retained paymentLink.payload |
listPaymentLinks | MakePayPaymentLinksResponse | required companyId; paymentLinks[] uses the same canonical partner-v1 link shape |
listDonationLinks | MakePayDonationLinksResponse | required companyId, donations |
sendPaymentRequestEmail | MakePayPaymentRequestEmailResponse | ok, email, and the updated payment-link email payload |
createAnonymousPaymentLink | MakePayAnonymousPaymentLinkResponse | anonymous, requestId, public paymentLink, and optional one-time webhook secret |
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 | MakePayBrandingResponse, MakePaySettingsResponse, or MakePaySettingsUpdateResponse | company, settings, ok |
listDestinationAssets, listWebhookRequests, current webhook subscription methods | operational response types | assets, webhook request logs, subscription metadata, and one-time signingSecret |
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.
API calls throw MakePayError with a numeric HTTP status. Remote error
bodies are intentionally not attached or reflected in the message, so the
error is safe to pass through normal application logging boundaries. The
deprecated responseBody property remains for source compatibility but is
always undefined.
import{MakePayError}from"@makecrypto/makepay";try{awaitmakepay.getPaymentLink("PAYMENT_LINK_UID");}catch(error){if(errorinstanceofMakePayError){console.error(error.status,error.message);}}