Integrate Macropay with Encore

Encore is an open-source TypeScript backend framework that turns your code into infrastructure: declare services, databases, and APIs, and Encore provisions and operates them for you, locally and in the cloud. It also captures distributed traces out of the box. That tracing pairs unusually well with a billing integration. Because both your services and your Macropay calls show up in the same trace, you (or an AI coding assistant reading the code and the traces together) can follow a single payment from the /checkout redirect, through the customer’s purchase, to the webhook that lands back in your handler — and see exactly where anything went sideways. And because Macropay is your merchant of record, that’s all you have to build. We’re the legal seller on the buyer’s statement, so we calculate and remit sales tax and VAT worldwide, keep PCI scope off your servers (cards are tokenized in our PCI DSS Level 1 compliant vault), and own chargebacks. You ship the Encore endpoints; we handle the global money plumbing.

Build against the Macropay Sandbox first. It mirrors production behavior — checkouts, orders, webhooks — without touching real money or live data.

What you’ll build

Endpoint	Encore pattern	Purpose
`GET /checkout`	`api.raw()`	Create a checkout session and redirect the buyer
`POST /webhooks/macropay`	`api.raw()`	Verify and process events (orders, subscriptions, customers)

Both use api.raw() so you control the raw HTTP request and response — required for redirects and for webhook signature verification, which depends on the exact bytes of the request body.

Install the SDK

Pull in the Macropay JavaScript SDK alongside the Standard Webhooks verification library:

Terminal

npm install @macropayments/sdk standardwebhooks

Store your secrets

Encore ships a secrets manager that behaves the same in local development and in the cloud, so you never hardcode credentials. You’ll need three values.

Access token and mode

Create an organization access token in your organization settings — this authenticates every API call. The mode flag tells the SDK whether to hit the sandbox or production environment.

Terminal

encore secret set --type local MACROPAY_ACCESS_TOKEN
encore secret set --type local MACROPAY_MODE

Set MACROPAY_MODE to sandbox while developing, and flip it to production when you go live.

Webhook secret

You’ll generate this when you register the webhook endpoint (see Handle webhooks). For now, reserve the slot:

Terminal

encore secret set --type local MACROPAY_WEBHOOK_SECRET

These commands set local secrets. For Encore Cloud, set the production values in the Encore dashboard or your CI/CD pipeline — covered under Deploy to production.

Initialize the client

Read the token and mode from Encore’s secret manager and construct a single shared Macropay instance you can import anywhere in your backend.

payments/macropay.ts

import { Macropay } from "@macropayments/sdk";
import { secret } from "encore.dev/config";

const MACROPAY_MODE = secret("MACROPAY_MODE");
const MACROPAY_ACCESS_TOKEN = secret("MACROPAY_ACCESS_TOKEN");

export const macropay = new Macropay({
  accessToken: MACROPAY_ACCESS_TOKEN(),
  server: MACROPAY_MODE() as "sandbox" | "production",
});

Create a checkout endpoint

This endpoint takes a product ID from the query string, opens a hosted checkout session, and 302-redirects the buyer to it. The same code works for a one-time purchase or a subscription — in Macropay both are just “products,” so the API call doesn’t change.

payments/payments.ts

import { api } from "encore.dev/api";
import { macropay } from "./macropay";

export const checkout = api.raw(
  { expose: true, path: "/checkout", method: "GET" },
  async (req, resp) => {
    const url = new URL(req.url!, `http://${req.headers.host}`);
    const productId = url.searchParams.get("product");

    if (!productId) {
      resp.writeHead(400);
      resp.end("Missing product query parameter");
      return;
    }

    try {
      const result = await macropay.checkouts.create({
        productId,
        successUrl: "https://your-app.com/welcome?checkout_id={CHECKOUT_ID}",
      });

      resp.writeHead(302, { Location: result.url });
      resp.end();
    } catch (error) {
      console.error("[Macropay] Checkout error:", error);
      resp.writeHead(500);
      resp.end("Failed to create checkout session");
    }
  }
);

Try it: open /checkout?product=YOUR_PRODUCT_ID. Macropay interpolates the real session ID into {CHECKOUT_ID} on the successUrl, so your post-purchase page can look the order up.

Handle webhooks

Macropay emits events as things happen in your organization — an order is created, a subscription activates or cancels, a customer’s state changes. Listening to these is how you keep your own database in sync, rather than polling the API.

Register the endpoint

In your organization settings, open the webhooks page and click Add Endpoint, then:

Set the URL

Point the endpoint at https://your-app.com/webhooks/macropay — an absolute URL Macropay can reach. During local development the Macropay CLI tunnel (below) supplies this for you.

Pick your events

Subscribe only to what you act on. See the full catalog in the webhook events reference.

Generate a signing secret

Macropay signs every delivery with this secret so you can prove the request really came from us. Copy it.

Store it in Encore

Terminal

encore secret set --type local MACROPAY_WEBHOOK_SECRET

Tunnel events to localhost

Encore runs your full app locally, so you just need to forward Macropay’s events to it. The Macropay CLI tunnels deliveries straight to your machine:

Terminal

macropay listen http://localhost:4000/webhooks/macropay

The CLI prints a webhook secret on startup — store that one for local testing:

Terminal

encore secret set --type local MACROPAY_WEBHOOK_SECRET

Write the handler

Use api.raw() so you can read the unparsed request body — signature verification runs against the exact bytes that were signed, so any reframing would invalidate it.

payments/payments.ts

import { api } from "encore.dev/api";
import { secret } from "encore.dev/config";
import { Webhook } from "standardwebhooks";

const MACROPAY_WEBHOOK_SECRET = secret("MACROPAY_WEBHOOK_SECRET");

export const webhooks = api.raw(
  { expose: true, path: "/webhooks/macropay", method: "POST" },
  async (req, resp) => {
    // Collect the raw request body
    const chunks: Buffer[] = [];
    for await (const chunk of req) {
      chunks.push(chunk);
    }
    const body = Buffer.concat(chunks).toString("utf-8");

    // Flatten headers into the shape standardwebhooks expects
    const headers: Record<string, string> = {};
    for (const [key, value] of Object.entries(req.headers)) {
      headers[key] = Array.isArray(value) ? value[0] : (value || "");
    }

    // Verify the signature before trusting anything
    let payload: any;
    try {
      const base64Secret = Buffer.from(
        MACROPAY_WEBHOOK_SECRET().trim(),
        "utf-8"
      ).toString("base64");
      const wh = new Webhook(base64Secret);
      payload = wh.verify(body, headers);
    } catch (error: any) {
      console.error("[Macropay] Invalid webhook signature:", error?.message);
      resp.writeHead(403);
      resp.end(JSON.stringify({ error: "Invalid signature" }));
      return;
    }

    // Route the verified event
    switch (payload.type) {
      case "order.created":
        console.log("[Macropay] Order created:", payload.data.id);
        break;
      case "subscription.active":
        console.log("[Macropay] Subscription active:", payload.data.id);
        break;
      case "subscription.canceled":
        console.log("[Macropay] Subscription canceled:", payload.data.id);
        break;
      case "customer.state_changed":
        console.log("[Macropay] Customer state changed:", payload.data.id);
        break;
      default:
        console.log("[Macropay] Unhandled event:", payload.type);
    }

    resp.writeHead(200);
    resp.end(JSON.stringify({ received: true }));
  }
);

standardwebhooks expects a base64-encoded secret. Macropay hands you a raw string (it starts with macropay_whs_), so base64-encode the entire secret before passing it to new Webhook() — as shown above. Skip this and verification fails on every delivery.

Run it locally

Terminal

encore run

Encore serves a local dashboard at localhost:9400. For a billing integration it earns its keep:

Distributed traces for every request — including the checkout redirect and each webhook delivery
Service-to-service calls laid out so you can see what your code did with an event
Local database queries to confirm your records updated
Live logs and errors as flows run

When a subscription fails to activate or a webhook doesn’t land, you open the trace instead of guessing — the request, the verification step, and your handler are all on one timeline.

Deploy to production

Ship to Encore Cloud (or your own cloud account) with:

Terminal

git push encore

Encore provisions the infrastructure automatically. Before flipping the switch, run down this list:

Set the production MACROPAY_ACCESS_TOKEN, MACROPAY_MODE, and MACROPAY_WEBHOOK_SECRET in the Encore Cloud dashboard.
Set MACROPAY_MODE to production so the SDK targets the live API.
Update the webhook endpoint in Macropay to your production domain.
Point successUrl at your production confirmation page.

Once you’re live, Macropay handles tax remittance, dispute management, and PCI compliance on every order those endpoints create — so the only thing left to maintain is your Encore backend.

Bootup

Features

Integrate

Merchant of Record (MoR)

Integrate Macropay with Encore

What you’ll build

Install the SDK

Store your secrets

Access token and mode

Webhook secret

Initialize the client

Create a checkout endpoint

Handle webhooks

Register the endpoint

Tunnel events to localhost

Write the handler

Run it locally

Deploy to production

​What you’ll build

​Install the SDK

​Store your secrets

​Access token and mode

​Webhook secret

​Initialize the client

​Create a checkout endpoint

​Handle webhooks

​Register the endpoint

​Tunnel events to localhost

​Write the handler

​Run it locally

​Deploy to production

What you’ll build

Install the SDK

Store your secrets

Access token and mode

Webhook secret

Initialize the client

Create a checkout endpoint

Handle webhooks

Register the endpoint

Tunnel events to localhost

Write the handler

Run it locally

Deploy to production