@mainpay/node

Typed server-side client for MainPay's non-custodial Orders API.

Install the optional convenience package:

npm install @mainpay/node

The raw REST quickstart works without the SDK. TypeScript projects should include @types/node, as usual for server-side Node code; the webhook helper accepts raw Buffer request bodies.

import MainPay from "@mainpay/node";

const mainpay = new MainPay(process.env.MAINPAY_API_KEY!);
const order = await mainpay.orders.create({
  fiat_amount: "25.00",
  asset: "USDC",
  network: "base",
  receiving_account_id: process.env.MAINPAY_WALLET_ID!,
  customer_name: "Checkout customer",
  client_reference_id: "user_123",
  metadata: { plan: "credits-100" },
  purpose: "credit_topup",
});

// Send only this URL to the browser. Never expose MAINPAY_API_KEY.
console.log(order.hosted_url);

Verify webhooks from their raw request bytes:

const event = mainpay.webhooks.constructEvent(
  rawBody,
  request.headers["x-mainpay-signature"],
  process.env.MAINPAY_WEBHOOK_SECRET!,
);

if (event.type === "invoice.paid") {
  // Deduplicate event.id, then grant credits in your own database using:
  // event.data.invoice.client_reference_id and event.data.invoice.metadata.
}

The browser-safe @mainpay/node/checkout export contains only openCheckout. It accepts a hosted_url returned by your server and never accepts an API key.