Integrate OurPay with Encore

Encore is an open source backend framework for TypeScript with built-in infrastructure automation and observability. When you define services, databases, and APIs in code, Encore automatically provisions and manages the underlying infrastructure, both locally and in the cloud. Because Encore defines infrastructure in code and provides built-in distributed tracing, AI coding assistants can both build and debug your backend end-to-end, including your OurPay integration. They can read the code to understand the full system, then inspect traces to diagnose exactly what happened when a checkout completes or a webhook arrives. Consider following this guide while using the OurPay Sandbox Environment. This will allow you to test your integration without affecting your production data.

Install the OurPay JavaScript SDK

Install the official OurPay SDK:

Terminal

npm install @ourpay-dev/sdk@next

Setting up Secrets

Encore has built-in secrets management that works consistently across local development and cloud environments.

OurPay Access Token and Mode

To authenticate with OurPay, you need to create an access token and specify if it’s production or sandbox mode. You can create an organization access token from your organization settings. Add it to Encore using the secrets manager:

Terminal

encore secret set --type local OURPAY_ACCESS_TOKEN
encore secret set --type local OURPAY_MODE

OurPay Webhook Secret

You’ll need a webhook secret to verify incoming webhook events. We’ll set this up in the webhook section below.

Terminal

encore secret set --type local OURPAY_WEBHOOK_SECRET

When deploying to Encore Cloud, you’ll set production secrets through the dashboard or CI/CD pipeline.

Configuring an OurPay API Client

To interact with the OurPay API, create a versioned client using Encore’s secret management.

payments/ourpay.ts

import { createOurPay } from "@ourpay-dev/sdk/2026-10";
import { secret } from "encore.dev/config";

const OURPAY_MODE = secret("OURPAY_MODE");
const OURPAY_ACCESS_TOKEN = secret("OURPAY_ACCESS_TOKEN");

export const ourpay = createOurPay({
  accessToken: OURPAY_ACCESS_TOKEN(),
  environment: OURPAY_MODE() as "sandbox" | "production",
});

Remember to set OURPAY_MODE as production when you’re ready to switch to the production environment.

Generating OurPay Checkout Sessions

Create a checkout endpoint that creates a OurPay checkout session and redirects the user.

payments/payments.ts

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

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 ourpay.checkouts.create({
        products: [productId],
        success_url: "https://your-app.com/confirmation?checkout_id={CHECKOUT_ID}",
      });

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

You can now create a checkout session by visiting /checkout?product=YOUR_PRODUCT_ID.

Handling OurPay Webhooks

OurPay can send you events about various things happening in your organization. This is useful for keeping your database in sync with OurPay checkouts, orders, subscriptions, etc. Configuring a webhook is simple. Head over to your organization’s settings page and click on the “Add Endpoint” button to create a new webhook.

Tunneling webhook events to your local development environment

Encore runs your app locally with full infrastructure support. Expose the local port through an HTTPS tunnel, then register its forwarding URL as a sandbox webhook endpoint:

Terminal

ngrok http 4000

Make sure to copy the webhook secret and set it using:

Terminal

encore secret set --type local OURPAY_WEBHOOK_SECRET

Add Webhook Endpoint

Point the Webhook to your-app.com/webhooks/ourpay. This must be an absolute HTTPS URL which OurPay can reach. During local development, use your tunnel origin plus /webhooks/ourpay.
Select which events you want to be notified about. You can read more about the available events in the Events section.
Generate a secret key to sign the requests. This will allow you to verify that the requests are truly coming from OurPay.
Add the secret key to Encore:

Terminal

encore secret set --type local OURPAY_WEBHOOK_SECRET

Setting up the Webhook handler

Encore webhook handlers use api.raw() to access the raw request body, which is required for signature verification.

payments/payments.ts

import { api } from "encore.dev/api";
import { secret } from "encore.dev/config";
import { webhooks as ourpayWebhooks } from "@ourpay-dev/sdk/2026-10";

const OURPAY_WEBHOOK_SECRET = secret("OURPAY_WEBHOOK_SECRET");

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

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

    let payload;
    try {
      payload = await ourpayWebhooks.validateEvent(
        body,
        headers,
        OURPAY_WEBHOOK_SECRET(),
      );
    } catch (error) {
      if (error instanceof ourpayWebhooks.OurPayWebhookVerificationError) {
        resp.writeHead(403);
        resp.end(JSON.stringify({ error: "Invalid signature" }));
        return;
      }
      if (error instanceof ourpayWebhooks.OurPayWebhookError) {
        resp.writeHead(400);
        resp.end(JSON.stringify({ error: "Invalid payload" }));
        return;
      }
      throw error;
    }

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

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

Local Development

Start your Encore app:

Terminal

encore run

Encore provides a local development dashboard at localhost:9400 where you can:

View distributed traces for all requests, including checkout redirects and webhook deliveries
Inspect API calls between services
Query local databases
View logs and errors in real-time

This makes debugging payment flows straightforward since you can trace exactly what happens when a checkout completes or a webhook arrives.

Deploying to Production

When you’re ready to go live, deploy to Encore Cloud or your own cloud account:

Terminal

git push encore

Encore automatically provisions all the infrastructure your app needs. Remember to:

Set production secrets in the Encore Cloud dashboard
Update the environment option from "sandbox" to "production" in your OurPay client
Update your webhook URL in OurPay to point to your production domain
Update success_url to your production URL

Bootup

Features

Integrate

Merchant of Record (MoR)

Integrate OurPay with Encore

Install the OurPay JavaScript SDK

Setting up Secrets

OurPay Access Token and Mode

OurPay Webhook Secret

Configuring an OurPay API Client

Generating OurPay Checkout Sessions

Handling OurPay Webhooks

Tunneling webhook events to your local development environment

Add Webhook Endpoint

Setting up the Webhook handler

Local Development

Deploying to Production

​Install the OurPay JavaScript SDK

​Setting up Secrets

​OurPay Access Token and Mode

​OurPay Webhook Secret

​Configuring an OurPay API Client

​Generating OurPay Checkout Sessions

​Handling OurPay Webhooks

​Tunneling webhook events to your local development environment

​Add Webhook Endpoint

​Setting up the Webhook handler

​Local Development

​Deploying to Production

Install the OurPay JavaScript SDK

Setting up Secrets

OurPay Access Token and Mode

OurPay Webhook Secret

Configuring an OurPay API Client

Generating OurPay Checkout Sessions

Handling OurPay Webhooks

Tunneling webhook events to your local development environment

Add Webhook Endpoint

Setting up the Webhook handler

Local Development

Deploying to Production