API Overview

Production Base URL

https://api.macropay.ai/v1

Sandbox Base URL

https://sandbox-api.macropay.ai/v1

Auth (Organization)

Use an Organization Access Token (OAT) in the Authorization: Bearer header

Auth (Customer Portal)

Use a Customer Access Token created via /v1/customer-sessions/

Base URLs

Environment	Base URL	Purpose
Production	`https://api.macropay.ai/v1`	Real customers & live payments
Sandbox	`https://sandbox-api.macropay.ai/v1`	Safe testing & integration work

The sandbox environment is fully isolated—data, users, tokens, and organizations created there do not affect production. Create separate tokens in each environment.

Authentication

Organization Access Tokens (OAT)

Use an OAT to act on behalf of your organization (manage products, prices, checkouts, orders, subscriptions, benefits, etc.).

Authorization: Bearer macropay_oat_xxxxxxxxxxxxxxxxx

Create OATs in your organization settings. See: Organization Access Tokens

Never expose an OAT in client-side code, public repos, or logs. If leaked, it will be revoked automatically by our secret scanning integrations.

Customer Access Tokens

Do not use OATs in the browser. For customer-facing flows, generate a Customer Session server-side, then use the returned customer access token with the Customer Portal API to let a signed-in customer view their own orders, subscriptions, and benefits.

Core API vs Customer Portal API

Aspect	Core API	Customer Portal API
Audience	Your server / backend	One of your customer
Auth Type	Organization Access Token (OAT)	Customer Access Token
Scope	Full org resources (products, orders, subscriptions, benefits, checkout)	Only the authenticated customer’s data
Typical Use	Admin dashboards, internal tools, automation, provisioning	Building a custom customer portal or gated app
Token Creation	Via dashboard (manual)	Via `/v1/customer-sessions/` (server-side)
Sensitive Operations	Yes (create/update products, issue refunds, etc.)	No (read/update only what the customer owns)

The Customer Portal API is a restricted surface designed for safe exposure in user-facing contexts (after exchanging a session). It cannot perform privileged org-level mutations like creating products or issuing refunds.

Quick Examples

curl https://api.macropay.ai/v1/products/ \
  -H "Authorization: Bearer $MACROPAY_OAT" \
  -H "Accept: application/json"

curl https://sandbox-api.macropay.ai/v1/products/ \
  -H "Authorization: Bearer $MACROPAY_OAT_SANDBOX" \
  -H "Accept: application/json"

curl https://api.macropay.ai/v1/customer-portal/orders/ \
  -H "Authorization: Bearer $MACROPAY_CUSTOMER_TOKEN" \
  -H "Accept: application/json"

Using SDKs

All official SDKs accept a server parameter for sandbox usage:

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

const macropay = new Macropay({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN!,
  server: "sandbox", // omit or use 'production' for live
});

from macropay import Macropay

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

s := macropaygo.New(
  macropaygo.WithServer("sandbox"),
  macropaygo.WithSecurity(os.Getenv("MACROPAY_ACCESS_TOKEN")),
)

$sdk = Macropay\Macropay::builder()
    ->setServer('sandbox')
    ->setSecurity(getenv('MACROPAY_ACCESS_TOKEN'))
    ->build();

Error Responses

All API errors follow a consistent format based on RFC 9457 (Problem Details):

{
  "type": "urn:macropay:error:resource-not-found",
  "title": "Resource Not Found",
  "detail": "The requested resource could not be found.",
  "status": 404,
  "request_id": "req_abc123...",
  "error": "ResourceNotFound"
}

Field	Type	Description
`type`	string	A stable URN identifying the error class
`title`	string	A human-readable summary of the error
`detail`	string	A more specific explanation of what went wrong
`status`	integer	The HTTP status code
`request_id`	string	A unique identifier for the request (useful for support)
`error`	string	The error class name (e.g., `ResourceNotFound`, `NotPermitted`)

Common Error Codes

Status	Error	Description
`400`	`BadRequest`	The request body or parameters are invalid
`401`	`Unauthorized`	Missing or invalid authentication token
`403`	`NotPermitted`	The token does not have the required scope
`404`	`ResourceNotFound`	The requested resource does not exist
`409`	`Conflict`	Resource is locked or in a conflicting state
`422`	`RequestValidationError`	Request body failed schema validation
`429`	`TooManyRequests`	Rate limit exceeded

Validation Errors

For 422 responses, the detail field contains an array of validation errors with the field path, error message, and error type:

{
  "type": "urn:macropay:error:request-validation-error",
  "title": "Request Validation Error",
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "status": 422,
  "request_id": "req_abc123..."
}

Idempotency Keys

For POST endpoints that create resources, you can include an X-Idempotency-Key header to safely retry requests without creating duplicate resources:

POST /v1/checkouts/ HTTP/1.1
Authorization: Bearer macropay_oat_xxx
X-Idempotency-Key: order_abc123_checkout
Content-Type: application/json

If a request with the same idempotency key has already been processed, the API will return the original response without creating a new resource. Keys are scoped to your organization and expire after 24 hours.

Use idempotency keys for any create operation that could be retried due to network failures, timeouts, or other transient errors.

Pagination

List endpoints in the Macropay API support pagination to help you efficiently retrieve large datasets. Use the page and limit query parameters to control pagination.

Query Parameters

Parameter	Type	Default	Max	Description
`page`	integer	`1`	-	Page number, starting from 1
`limit`	integer	`10`	`100`	Number of items to return per page (window size)

The page parameter works as a window offset. For example, page=2&limit=10 means the API will skip the first 10 elements and return the next 10.

Response Format

All paginated responses include a pagination object with metadata about the current page and total results:

Field	Type	Description
`total_count`	integer	Total number of items matching your query across all pages
`max_page`	integer	Total number of pages available, given the current `limit` value

Example

Let’s say you want to fetch products with a limit of 100 items per page:

curl https://api.macropay.ai/v1/products/?page=1&limit=100 \
  -H "Authorization: Bearer $MACROPAY_OAT" \
  -H "Accept: application/json"

{
  "items": [
    {
      "id": "...",
      "name": "Product 1",
      ...
    },
    ...
  ],
  "pagination": {
    "total_count": 250,
    "max_page": 3
  }
}

In this example:

total_count=250 indicates there are 250 total products
limit=100 means each page contains up to 100 products
max_page=3 means you need to make 3 requests to retrieve all products (pages 1, 2, and 3)

To retrieve all pages, increment the page parameter from 1 to max_page. Our SDKs provide built-in pagination helpers to automatically iterate through all pages.

Rate Limits

Macropay API has rate limits to ensure fair usage and maintain performance. The limits are as follows:

300 requests per minute per organization/customer or OAuth2 Client.
3 requests per second for unauthenticated license key validation, activation, and deactivation endpoints.

If you exceed the rate limit, you will receive a 429 Too Many Requests response. The response will include a Retry-After header indicating how long you should wait before making another request.

Organizations requiring higher rate limits for production workloads may contact our support team to discuss elevated limits.

General

Core API

Customer Portal API

Webhook Events

Integrations

Production Base URL

Sandbox Base URL

Auth (Organization)

Auth (Customer Portal)

Base URLs

Authentication

Organization Access Tokens (OAT)

Customer Access Tokens

Core API vs Customer Portal API

Quick Examples

Using SDKs

Error Responses

Common Error Codes

Validation Errors

Idempotency Keys

Query Parameters

Response Format

Example

Rate Limits

Production Base URL

Sandbox Base URL

Auth (Organization)

Auth (Customer Portal)

​Base URLs

​Authentication

​Organization Access Tokens (OAT)

​Customer Access Tokens

​Core API vs Customer Portal API

​Quick Examples

​Using SDKs

​Error Responses

​Common Error Codes

​Validation Errors

​Idempotency Keys

​Pagination

​Query Parameters

​Response Format

​Example

​Rate Limits

Base URLs

Authentication

Organization Access Tokens (OAT)

Customer Access Tokens

Core API vs Customer Portal API

Quick Examples

Using SDKs

Error Responses

Common Error Codes

Validation Errors

Idempotency Keys

Pagination

Query Parameters

Response Format

Example

Rate Limits