Quickstart

The fastest path to revenue: define what you sell, hand a customer a link, and let Macropay clear the payment for you. Because Macropay is your merchant of record, that same call also makes us the legal seller — we calculate and remit sales tax and VAT worldwide, keep you out of PCI scope, and own the dispute process. You write code; we carry the compliance. By the end of this guide you’ll have a live product, a working checkout, a completed test sale, and a signed webhook landing in your app.

What you’ll need

A Macropay account
An organization set up in the dashboard

Run everything in the Sandbox environment. Sandbox mirrors production but never moves real money or touches a real card.

Authenticate with an access token

Macropay authenticates server-side requests with an Organization Access Token (OAT) — a long-lived key scoped to one organization.

Open your organization Settings in the dashboard
Go to Access Tokens
Click Create Token and copy the value (you’ll only see it once)

export MACROPAY_ACCESS_TOKEN="macropay_oat_your_token_here"

Create a product

In Macropay, everything you sell is a product — one-time or recurring, same API. Here we’ll stand up a monthly “Indie tier” subscription at $12/month (price_amount is in cents).

curl -X POST https://api.macropay.ai/v1/products/ \
  -H "Authorization: Bearer $MACROPAY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Indie tier",
    "prices": [
      {
        "type": "recurring",
        "recurring_interval": "month",
        "price_amount": 1200,
        "price_currency": "usd"
      }
    ]
  }'

import { Macropay } from "@macropayments/sdk";

const macropay = new Macropay({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN!,
  server: "sandbox",
});

const product = await macropay.products.create({
  name: "Indie tier",
  prices: [
    {
      type: "recurring",
      recurringInterval: "month",
      priceAmount: 1200,
      priceCurrency: "usd",
    },
  ],
});

console.log("Product created:", product.id);

from macropay import Macropay
import os

client = Macropay(
    access_token=os.environ["MACROPAY_ACCESS_TOKEN"],
    server="sandbox",
)

product = client.products.create(
    name="Indie tier",
    prices=[
        {
            "type": "recurring",
            "recurring_interval": "month",
            "price_amount": 1200,
            "price_currency": "usd",
        }
    ],
)

print(f"Product created: {product.id}")

Result: a product.id in the response. Hold onto it — the next step needs it.

Generate a checkout link

A checkout turns a product into a hosted, PCI-compliant payment page. Card data is tokenized in our PCI DSS Level 1 vault — it never reaches your server, so you stay out of PCI scope entirely.

curl -X POST https://api.macropay.ai/v1/checkouts/ \
  -H "Authorization: Bearer $MACROPAY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "YOUR_PRODUCT_ID",
    "success_url": "https://example.com/success"
  }'

const checkout = await macropay.checkouts.create({
  productId: product.id,
  successUrl: "https://example.com/success",
});

console.log("Checkout URL:", checkout.url);

checkout = client.checkouts.create(
    product_id=product.id,
    success_url="https://example.com/success",
)

print(f"Checkout URL: {checkout.url}")

Result: open the returned url in a browser and you’ll see the live checkout. Share it as a link, drop it in an email, or embed it in your app.

Run a test sale

Sandbox accepts canonical test cards. Use these to simulate a successful payment:

Field	Value
Card number	`4242 4242 4242 4242`
Expiry	Any future date
CVC	Any 3 digits
Name	Any name
Email	An address you control

Finish the form and Macropay redirects you to your success_url. Behind the scenes, the sale is recorded, tax is computed for the buyer’s region, and a customer record is created — no extra calls from you.

Receive a signed webhook

Webhooks are how your backend learns that money moved. Register an endpoint and subscribe to the events you care about.

curl

curl -X POST https://api.macropay.ai/v1/webhooks/endpoints \
  -H "Authorization: Bearer $MACROPAY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/api/webhooks/macropay",
    "events": [
      "checkout.created",
      "checkout.updated",
      "order.created",
      "order.paid",
      "subscription.created",
      "subscription.active"
    ],
    "format": "raw"
  }'

No public URL yet? Expose your local server with a tunnel like ngrok, or skip the tunnel entirely with our local webhook testing CLI.

When the test sale clears, you’ll receive an order.paid payload:

{
  "type": "order.paid",
  "data": {
    "id": "ord_xxx",
    "status": "paid",
    "product": {
      "id": "prod_xxx",
      "name": "Indie tier"
    },
    "customer": {
      "id": "cust_xxx",
      "email": "customer@example.com"
    },
    "amount": 1200,
    "currency": "usd"
  }
}

In production, always verify the webhook signature before trusting a payload. Macropay signs every delivery using the Standard Webhooks spec.

You just shipped a billable product

In a handful of calls you created a product, took a payment, and got a verified server-side event — with tax, PCI, and dispute handling folded in for free. The same primitives scale well past a single subscription. A few directions worth exploring:

Billing AI and agents by what they do. Macropay can meter usage, activity, or outcomes — bill an agent for the revenue it generated or the time it saved, and watch its margin against AI cost.
Drop in an OpenAI-compatible proxy. Point your LLM calls at /ai/v1/chat/completions and Macropay captures token cost per request automatically.
Let customers self-serve. The hosted customer portal handles upgrades, cancellations, and invoices without you building a settings page.

Pricing models

Fixed, free, pay-what-you-want, usage-based, and seat-based pricing

Webhook events

Every event type you can subscribe to

Customer portal

Self-serve upgrades, invoices, and cancellations

SDKs

TypeScript, Python, PHP, and Go libraries

Bootup

Features

Integrate

Merchant of Record (MoR)

What you’ll need

You just shipped a billable product

Pricing models

Webhook events

Customer portal

SDKs

​What you’ll need

​You just shipped a billable product

Pricing models

Webhook events

Customer portal

SDKs

What you’ll need

You just shipped a billable product