Quickstart

This guide creates a marketplace checkout session and redirects the browser to its one-time URL.

Prerequisites

An approved Payments service client ID and secret
A billing account your client is allowed to access
A ready merchant account for the current environment
Registered return and cancel URLs

Store the service credential

Keep both values in your backend environment:

BOXPRESSD_PAYMENTS_CLIENT_ID=your-service-client
BOXPRESSD_PAYMENTS_CLIENT_SECRET=replace_me
BOXPRESSD_PAYMENTS_ORIGIN=https://payments-dev.boxpressd.com

Never expose the secret through browser or native application code.

Create a hosted session

Call Payments from your backend. Supply a stable idempotency key for the checkout attempt.

const response = await fetch(
  `${process.env.BOXPRESSD_PAYMENTS_ORIGIN}/api/v1/payment-sessions`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BOXPRESSD_PAYMENTS_CLIENT_SECRET}`,
      "X-Boxpressd-Client-Id": process.env.BOXPRESSD_PAYMENTS_CLIENT_ID,
      "Idempotency-Key": order.checkoutAttemptId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      action: "purchase",
      actor: { type: "boxpressd_user", id: String(user.id) },
      billingAccountId: order.billingAccountId,
      marketplace: {
        merchantAccountId: order.merchantAccountId,
        orderReference: order.id,
        money: { amountMinor: order.totalMinor, currency: "USD" },
      },
      returnUrl: `https://shop.example/orders/${order.id}/complete`,
      cancelUrl: `https://shop.example/orders/${order.id}`,
      presentation: "page",
    }),
  },
);

const { data } = await response.json();

Use the first returned URL

Redirect the browser to data.url or open it with the embed SDK.Persist the session ID before redirecting. An idempotency replay returns the existing session with url: null because Payments cannot reproduce the raw one-time token.

Verify authoritative status

After the user returns, query the session from your backend:

const response = await fetch(
  `${process.env.BOXPRESSD_PAYMENTS_ORIGIN}/api/v1/payment-sessions/${sessionId}/status`,
  {
    headers: {
      Authorization: `Bearer ${process.env.BOXPRESSD_PAYMENTS_CLIENT_SECRET}`,
      "X-Boxpressd-Client-Id": process.env.BOXPRESSD_PAYMENTS_CLIENT_ID,
    },
  },
);

const { data: status } = await response.json();

Browser status messages improve the interface but do not prove fulfillment. Use the status endpoint or the signed fulfillment callback as your source of truth.

Getting started

Integrate

Credits and billing

Prerequisites

​Prerequisites

Prerequisites