Integration Guide

Basic Integration

Create sessions from your backend. Do not expose an OpenCheckout API key in browser JavaScript. Browser CORS access is disabled unless an operator explicitly configures CORS_ALLOWED_ORIGINS.

1. Backend: Create a session

When a customer wants to check out, your backend creates a session via the OpenCheckout API:

// Node.js example
const response = await fetch("https://checkout.yourdomain.com/api/checkout/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENCHECKOUT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": orderId, // Prevent duplicates
  },
  body: JSON.stringify({
    mode: "payment",
    line_items: cart.items.map(item => ({
      price_data: {
        currency: "usd",
        product_data: {
          name: item.name,
          description: item.description,
        },
        unit_amount: item.price_cents,
      },
      quantity: item.quantity,
    })),
    success_url: `https://yourstore.com/orders/${orderId}/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: "https://yourstore.com/cart",
    metadata: { order_id: orderId },
  }),
});

const session = await response.json();
// Redirect customer to session.url
res.redirect(session.url);

2. Frontend: Redirect to checkout

<a href="{{ session.url }}">Proceed to Checkout</a>

3. Backend: Handle success

When the customer returns to your success_url, verify the session:

// On your success page
const sessionId = new URL(req.url).searchParams.get("session_id");
const response = await fetch(
  `https://checkout.yourdomain.com/api/checkout/sessions/${sessionId}`,
  { headers: { Authorization: `Bearer ${process.env.OPENCHECKOUT_API_KEY}` } }
);
const session = await response.json();

if (session.status === "completed") {
  // Fulfill order
}

4. Backend: Listen for webhooks (recommended)

For reliability, also listen for webhooks — the redirect might not arrive:

app.post("/webhooks/opencheckout", (req, res) => {
  const signature = req.headers["opencheckout-signature"];
  // Verify signature using your webhook secret
  // See API Reference for verification details

  const event = req.body;
  if (event.status === "completed") {
    // Fulfill order referenced in event.metadata.order_id
  }

  res.sendStatus(200);
});

Use Cases

eCommerce

The payment mode handles one-time purchases. Create a session with line items, redirect the customer, and fulfill on completion.

Donations and subscriptions

OpenCheckout currently supports one-time payment sessions. Donation and subscription modes are intentionally rejected by the API until those flows have complete Open Payments orchestration, dashboard reporting, and webhook semantics.

Marketplaces

For marketplace scenarios where you split payments:

1. Buyer pays your marketplace wallet
2. Your backend creates outgoing payments to each seller
3. Each seller receives funds through their own OpenCheckout instance or wallet

Error Handling

HTTP Status	Type	Meaning
401	authentication_error	Invalid or missing API key
400	invalid_request_error	Malformed request body
404	not_found	Session not found
409	idempotency_error	Key is in progress or was reused with a different request
500	api_error	Server error — retry