Skip to main content
A checkout session is a short-lived, hosted payment page you generate on demand and hand to a customer. Because Macropay is the merchant of record, that one call does more than collect a card: we calculate and remit the right sales tax or VAT for the buyer’s country, keep card data inside our PCI DSS Level 1 compliant vault, and appear as the seller of record on the statement — so the liability never lands on you. This guide walks through creating a session over the API, from token to live checkout URL.
Pass one or more products into a session and the customer can switch between them on the page. Everything in Macropay is a product — one-time or subscription — so the same flow powers a single license sale or a recurring plan.

​
What you’ll need

  • An organization access token (created below)
  • One or more product IDs from your catalogue
  • A terminal with curl, or any HTTP client / SDK
1

Create an organization access token

Sessions are created with an organization access token (OAT). Generate one by following the Organization Access Tokens guide.
2

Copy the token immediately

The token is shown once at creation time. Copy it and store it in a secret manager or environment variable — you won’t be able to view it again.
3

Open your product catalogue

In the Macropay dashboard sidebar, go to Products > Catalogue, or jump straight to the catalogue for your organization:https://macropay.ai/dashboard/${org_slug}/products
4

Grab the product IDs

For each item you want to offer, open the ⋮ (More options) menu next to the product and choose Copy Product ID. Collect the IDs you need for the next step.
5

Create the session

Send a POST to the checkouts endpoint with the products you want available on the page. Replace <YOUR_ACCESS_TOKEN> with your token and the placeholder UUIDs with your real product IDs.
Terminal
success_url, customer_email, external_customer_id, and metadata are all optional. Use external_customer_id to tie the order to a user in your own system, and metadata to stamp the session with anything you want echoed back on the resulting order and webhook events.
Every accepted field is documented in the Create Checkout Session API reference.
6

Redirect the customer to the URL

The response is a checkout object. Read the url field and send the customer there — that’s the hosted, tax-aware payment page.
The tax_amount is computed for the buyer’s location and remitted by us — you keep your net_amount without touching a tax return.

​
Selling to AI agents

The same endpoint works when the buyer is an autonomous agent rather than a person. Create a session, hand back the url, and let the agent complete payment programmatically. To bill agents by what they actually do, pair checkout with usage-based pricing so you can charge on activity or verified outcome and track agentic margin per agent. See the API reference for the signals and metering endpoints.

​
Next steps

Checkout Links

Skip the API and share a no-code, reusable payment link.

Embedded Checkout

Drop checkout straight into your own site instead of redirecting.