> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macropay.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Sell something in five minutes. As merchant of record, Macropay handles tax, compliance, and disputes — you ship a checkout link and collect a webhook.
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](https://macropay.ai/signup)
* An organization set up in the dashboard
Run everything in the [Sandbox environment](https://sandbox.macropay.ai/start). Sandbox mirrors production but never moves real money or touches a real card.
Macropay authenticates server-side requests with an **Organization Access Token (OAT)** — a long-lived key scoped to one organization.
1. Open your organization **Settings** in the dashboard
2. Go to **Access Tokens**
3. Click **Create Token** and copy the value (you'll only see it once)
```bash theme={null}
export MACROPAY_ACCESS_TOKEN="macropay_oat_your_token_here"
```
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).
```bash curl theme={null}
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"
}
]
}'
```
```ts TypeScript theme={null}
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);
```
```py Python theme={null}
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.
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.
```bash curl theme={null}
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"
}'
```
```ts TypeScript theme={null}
const checkout = await macropay.checkouts.create({
productId: product.id,
successUrl: "https://example.com/success",
});
console.log("Checkout URL:", checkout.url);
```
```py Python theme={null}
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.
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.
Webhooks are how your backend learns that money moved. Register an endpoint and subscribe to the events you care about.
```bash curl theme={null}
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](https://ngrok.com), or skip the tunnel entirely with our [local webhook testing CLI](/integrate/webhooks/locally).
When the test sale clears, you'll receive an `order.paid` payload:
```json theme={null}
{
"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](/integrate/webhooks/verification) 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*](/features/usage-based-billing/meters) — 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](/features/customer-portal) handles upgrades, cancellations, and invoices without you building a settings page.
Fixed, free, pay-what-you-want, usage-based, and seat-based pricing
Every event type you can subscribe to
Self-serve upgrades, invoices, and cancellations
TypeScript, Python, PHP, and Go libraries