TypeScript SDK

The @macropayments/sdk package is the fastest way to talk to Macropay from any JavaScript runtime. It ships full TypeScript types, async pagination helpers, and covers the entire v1 API — from hosted checkout to usage meters to agent Signals. Because Macropay is your merchant of record, the same calls that move money also handle sales tax, VAT, and PCI scope on your behalf.

Install

npm
pnpm
yarn

Terminal

npm install @macropayments/sdk

Terminal

pnpm add @macropayments/sdk

Terminal

yarn add @macropayments/sdk

Configure the client

Create one Macropay instance and reuse it. Point it at sandbox while you build, then flip the env var to production when you go live — no code changes.

macropay.ts

import { Macropay } from '@macropayments/sdk'

export const macropay = new Macropay({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN,
  server: process.env.MACROPAY_MODE || 'sandbox', // 'sandbox' | 'production'
})

Generate an Organization Access Token (OAT) in the dashboard and store it as MACROPAY_ACCESS_TOKEN. Never ship a token to the browser — keep checkout and billing calls server-side.

Your first call

List operations return an async iterator, so paging through results is a single for await loop. Here we walk every benefit a customer has unlocked — license keys, downloads, Discord access, and so on.

list-benefits.ts

import { macropay } from './macropay'

async function run() {
  const result = await macropay.users.benefits.list({})

  for await (const page of result) {
    console.log(page) // each page of granted benefits
  }
}

run()

Spin up a checkout

Everything you sell — one-time or subscription — is a product, so the call shape is identical. Create a checkout session and redirect the customer to the hosted, fully localized payment page:

checkout.ts

import { macropay } from './macropay'

const checkout = await macropay.checkouts.create({
  products: ['prod_starter_plan'],
  successUrl: 'https://example.com/thanks',
})

// Send the buyer here — card data is tokenized in our PCI DSS Level 1 vault.
return Response.redirect(checkout.url)

Tax is calculated, collected, and remitted by Macropay as the seller of record, so the merchant of record on the buyer’s statement is us — not you.

Meter AI and agent usage

Bill for what your product actually does — tokens consumed, actions taken, or outcomes delivered — by ingesting events. Meters aggregate those events into a metered price, and you can certify agent ROI with value receipts.

ingest-usage.ts

import { macropay } from './macropay'

// Report metered usage (e.g. tokens an agent burned this run)
await macropay.events.ingest({
  events: [
    {
      name: 'ai_tokens',
      externalCustomerId: 'cus_acme',
      metadata: { tokens: 12_480, model: 'gpt-4o-mini' },
    },
  ],
})

Routing model calls through the OpenAI-compatible AI proxy at /ai/v1 captures token cost automatically — no manual event ingestion needed. See the proxy and agent-billing flows in the adapter guides.

camelCase in TypeScript

The Macropay API and reference docs use snake_case, but this SDK exposes camelCase to match JS/TS convention. Modern editors surface the camelCase fields via the bundled types, so the mapping is usually invisible — just keep it in mind when copying field names straight from the API reference.

In the docs (API)	In the SDK
`success_url`	`successUrl`
`external_customer_id`	`externalCustomerId`
`metered_price`	`meteredPrice`

A future release will let you opt into snake_case in TypeScript so SDK code maps one-to-one with the API design and documentation.

Framework adapters

Wire up hosted checkout and signature-verified webhook handlers in a handful of lines — pick the adapter for your stack:

Bootup

Features

Integrate

Merchant of Record (MoR)

Install

Configure the client

Your first call

Spin up a checkout

Meter AI and agent usage

camelCase in TypeScript

Framework adapters

Next.js

Express

Hono

Fastify

Remix

SvelteKit

Nuxt

Astro

Elysia

TanStack Start

Deno

Better Auth

​Install

​Configure the client

​Your first call

​Spin up a checkout

​Meter AI and agent usage

​camelCase in TypeScript

​Framework adapters

Next.js

Express

Hono

Fastify

Remix

SvelteKit

Nuxt

Astro

Elysia

TanStack Start

Deno

Better Auth

Install

Configure the client

Your first call

Spin up a checkout

Meter AI and agent usage

camelCase in TypeScript

Framework adapters