​
Prerequisites

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

​
Step 1: Create an Access Token

Generate an Organization Access Token (OAT) to authenticate API requests.
  1. Go to your organization Settings in the Macropay dashboard
  2. Navigate to Access Tokens
  3. Click Create Token and copy the token
export MACROPAY_ACCESS_TOKEN="macropay_oat_your_token_here"

​
Step 2: Create a Product

curl -X POST https://api.macropay.com/v1/products/ \
  -H "Authorization: Bearer $MACROPAY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Plan",
    "prices": [
      {
        "type": "recurring",
        "recurring_interval": "month",
        "price_amount": 1999,
        "price_currency": "usd"
      }
    ]
  }'
Save the product.id from the response — you will need it in the next step. Create a checkout session that your customers can use to purchase the product. 
curl -X POST https://api.macropay.com/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"
  }'
Open the returned url in your browser to see the checkout page.

​
Step 4: Accept a Test Payment

In the sandbox environment, use the following test card details:
FieldValue
Card number4242 4242 4242 4242
ExpiryAny future date
CVCAny 3 digits
NameAny name
EmailYour email address
Complete the checkout. You should be redirected to your success URL.

​
Step 5: Receive a Webhook

Set up a webhook endpoint to get notified about events like successful payments.

​
Create a Webhook Endpoint

curl -X POST https://api.macropay.com/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"
  }'
For local development, use a tunneling tool like ngrok to expose your local server to the internet, or use our CLI for local webhook testing.

​
Handle the Webhook

When a payment completes, you will receive an order.paid event: 
{
  "type": "order.paid",
  "data": {
    "id": "ord_xxx",
    "status": "paid",
    "product": {
      "id": "prod_xxx",
      "name": "Pro Plan"
    },
    "customer": {
      "id": "cust_xxx",
      "email": "customer@example.com"
    },
    "amount": 1999,
    "currency": "usd"
  }
}
Always verify webhook signatures in production to ensure the events are genuinely from Macropay.

​
What’s Next?

Products

Create more products with different pricing models

Webhook Events

Learn about all available webhook event types

Customer Portal

Set up self-service for your customers

SDKs

Integrate with your preferred language