​
Prerequisites

We recommend using the Sandbox environment for this guide so you can test without processing real payments.

​
Step 1: Install the SDK

pip install macropay
Set your access token as an environment variable: 
export MACROPAY_ACCESS_TOKEN="macropay_oat_your_token_here"
export MACROPAY_WEBHOOK_SECRET="whsec_your_secret_here"

​
Step 2: Initialize the Client

from macropay import Macropay
import os

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

​
Step 3: Create a Checkout Session

Create a product in the dashboard first, then generate a checkout session programmatically: 
checkout = client.checkouts.create(
    product_id="prod_xxx",
    success_url="https://your-app.com/success",
)

print(f"Checkout URL: {checkout.url}")
# Redirect your customer to this URL

​
Step 4: Handle Webhooks

Set up a webhook endpoint to process payment events. Here is a complete FastAPI example with signature verification: 
# webhook.py
from fastapi import FastAPI, Request, HTTPException
from standardwebhooks.webhooks import Webhook
import os

app = FastAPI()

WEBHOOK_SECRET = os.environ["MACROPAY_WEBHOOK_SECRET"]

@app.post("/api/webhooks/macropay")
async def handle_webhook(request: Request):
    body = await request.body()
    body_str = body.decode("utf-8")

    headers = {
        "webhook-id": request.headers.get("webhook-id"),
        "webhook-timestamp": request.headers.get("webhook-timestamp"),
        "webhook-signature": request.headers.get("webhook-signature"),
    }

    wh = Webhook(WEBHOOK_SECRET)

    try:
        payload = wh.verify(body_str, headers)
    except Exception:
        raise HTTPException(status_code=401, detail="Invalid signature")

    event_type = payload["type"]

    if event_type == "order.paid":
        order = payload["data"]
        # Provision access, update database
        print(f"Order paid: {order['id']}")

    elif event_type == "subscription.created":
        subscription = payload["data"]
        # Grant access to your product
        print(f"New subscription: {subscription['id']}")

    elif event_type == "subscription.canceled":
        subscription = payload["data"]
        # Revoke access
        print(f"Subscription canceled: {subscription['id']}")

    return {"status": "ok"}
Install the webhook verification library: 
pip install standardwebhooks
Register your webhook endpoint in the Macropay dashboard under Settings > Webhooks. For local development, use ngrok to expose your local server.

​
Step 5: Query Orders and Subscriptions

Once payments are flowing, query your data: 
# List orders
orders = client.orders.list()
for order in orders.result:
    print(f"Order {order.id}: {order.status} - ${order.amount / 100:.2f}")

# List subscriptions
subscriptions = client.subscriptions.list()
for sub in subscriptions.result:
    print(f"Subscription {sub.id}: {sub.status}")

# Get a specific customer
customer = client.customers.get(customer_id="cust_xxx")
print(f"Customer: {customer.email}")

​
Step 6: Test with Sandbox

  1. Create a checkout session and open the returned URL
  2. Use the test card 4242 4242 4242 4242 with any future expiry and any CVC
  3. Complete the purchase
  4. Verify the webhook fires in your terminal
When you are ready for production:
  • Replace your sandbox access token with a production token
  • Change server="sandbox" to server="production" (or remove it entirely)
  • Update your webhook endpoint URL to your production domain
  • API base URL changes from sandbox-api.macropay.com to api.macropay.com

​
What’s Next?

AI/LLM Billing

Bill customers based on AI model usage

Webhook Events

See all available webhook event types

Python SDK Reference

Full SDK documentation

Customer Portal

Let customers manage their subscriptions