API reference

The production API base URL is https://payments.boxpressd.com/api/v1. Approved backends authenticate with both Authorization: Bearer <service-client-secret> and X-Boxpressd-Client-Id.

Trusted service endpoints

Method	Path	Purpose
`POST`	`/billing-accounts/resolve`	Resolve an assertion-authorized billing account and current balance.
`POST`	`/billing-accounts/auto-reload`	Configure assertion-authorized automatic credit reload.
`GET`	`/offers?resourceType={type}`	List active offers available to a registered resource type.
`POST`	`/payment-sessions`	Create a short-lived hosted session.
`GET`	`/payment-sessions/{id}/status`	Get authoritative session and purchase status.
`GET`	`/merchant-accounts`	List merchant configuration status for an authorized owner.
`POST`	`/merchant-accounts`	Create an authorized merchant account.
`PUT`	`/merchant-accounts/{id}/credentials`	Configure or rotate gateway credentials.
`DELETE`	`/merchant-accounts/{id}/credentials`	Revoke gateway credentials.

Merchant routes require merchant_accounts:read or merchant_accounts:write. Responses expose configuration status but never return a gateway secret, encrypted credential, or vault reference.

Hosted-browser endpoints

These routes require the signed, HttpOnly action cookie created when the browser redeems a one-time session:

Method	Path	Purpose
`POST`	`/payment-sessions/redeem`	Redeem the one-time URL token.
`GET`	`/payment-sessions/current`	Load the active hosted session.
`POST`	`/payment-sessions/current/cancel`	Cancel the active session.
`GET`, `POST`	`/payment-methods`	List or add payment methods.
`PATCH`	`/payment-methods/{id}/default`	Make a method the default.
`DELETE`	`/payment-methods/{id}`	Remove a saved method.
`POST`	`/purchase-intents/{id}/confirm`	Confirm and capture the active purchase.

Raw card data is accepted only by POST /api/pci/v1/payment-methods on the Payments origin. Caller backends and parent applications must not proxy or log that payload.

Idempotency

POST /payment-sessions requires Idempotency-Key. The purchase confirmation and server-managed offer creation routes also require it. Use a stable key for one logical attempt, and generate a new key only for new work.

Common errors

Status	Error	Meaning
`400`	`idempotency_key_required`	A required idempotency key is missing or invalid.
`400`	`return_not_allowed`	The return or cancel URL is not registered.
`400`	`origin_not_allowed`	The iframe parent origin is not registered.
`401`	Authentication error	The service client or hosted action session is invalid.
`403`	`action_not_allowed`	The client policy does not allow the requested action.
`403`	`billing_account_assertion_required`	This client must prove account-specific authorization.
`404`	`merchant_account_not_found`	The merchant is not ready in this environment.
`409`	`merchant_not_ready`	The server-configured offer cannot use its merchant account yet.
`410`	`session_unavailable`	The one-time hosted session is invalid, expired, or already redeemed.

Errors use a JSON object with error and message fields.

Verify fulfillment callbacks

Payments signs the exact raw request body with HMAC-SHA256. The signature header uses v1=<hex-digest>.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyPaymentsCallback({ rawBody, timestamp, signature }) {
  const sentAt = Number(timestamp);
  if (!Number.isFinite(sentAt) || Math.abs(Date.now() / 1000 - sentAt) > 300) {
    return false;
  }

  const expected = `v1=${createHmac(
    "sha256",
    process.env.BOXPRESSD_PAYMENTS_WEBHOOK_SECRET,
  )
    .update(`${timestamp}.${rawBody}`)
    .digest("hex")}`;

  const actualBytes = Buffer.from(signature);
  const expectedBytes = Buffer.from(expected);

  return (
    actualBytes.length === expectedBytes.length &&
    timingSafeEqual(actualBytes, expectedBytes)
  );
}

Read X-Boxpressd-Timestamp and X-Boxpressd-Signature before parsing the body. Reject stale timestamps, verify the signature against the raw bytes, and deduplicate the event id before applying fulfillment. Return a successful status only after the event has been recorded durably.

Getting started

Integrate

Credits and billing

Trusted service endpoints

Hosted-browser endpoints

Idempotency

Common errors

Verify fulfillment callbacks

​Trusted service endpoints

​Hosted-browser endpoints

​Idempotency

​Common errors

​Verify fulfillment callbacks

Trusted service endpoints

Hosted-browser endpoints

Idempotency

Common errors

Verify fulfillment callbacks