Getting started

Every integration begins on your server. Choose an environment, load the matching secret API key from secret storage, and create a checkout session from your authoritative cart or order.

Checkout-session bodies are strict: an unrecognized top-level property, or an unrecognized property inside an item, returns 422 Unprocessable Entity. Send only the fields declared by the API reference.

Integration sequence

1. Select sandbox or live and configure the corresponding API base on your server.
2. Create a checkout session with a merchant API key. A channel acting for a merchant also identifies that merchant as described in Channel API.
3. Give the buyer Hosted Checkout or Embedded Checkout, or mount the published browser SDK by following the maxanapay.js reference.
4. Treat the browser result as user experience feedback. Reconcile durable state from the API and webhooks, with duplicate-safe handling.

Checkout session examples

The cURL and Node.js examples create a sandbox checkout session from trusted server code. The browser example mounts that session after your page loads the published major-channel script; it explicitly selects the sandbox API.

cURLBrowser TypeScriptNode.js TypeScriptRequest JSONResponse JSON

curl.sh

curl --request POST \
  --url https://staging.api.maxanapay.com/api/checkout-sessions \
  --header 'Authorization: Bearer sk_test_replace_me' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order_1001_checkout' \
  --data @request.json

browser.ts

// The browser example mounts that session after your page loads the published major-channel script; it explicitly selects the sandbox API.
const sdkScript = document.createElement('script');
sdkScript.src = 'https://js.maxanapay.com/v1/maxanapay.js';
sdkScript.addEventListener('load', () => {
  const checkout = MaxanaPay.checkout({
    sessionId: 'cs_replace_me',
    container: '#maxana-checkout',
    environment: 'sandbox',
    onApproved(payment) {
      window.location.assign(`/orders/${payment.orderId}`);
    },
    onError(error) {
      console.error(error.code, error.retryable);
    },
  });

  window.addEventListener('pagehide', () => checkout.unmount());
});
document.head.append(sdkScript);

server.ts

import requestPayload from './request.json' with { type: 'json' };

const response = await fetch(
  'https://staging.api.maxanapay.com/api/checkout-sessions',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.MAXANA_SECRET_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': 'order_1001_checkout',
    },
    body: JSON.stringify(requestPayload),
  },
);

if (!response.ok) {
  throw new Error(`Checkout session failed with HTTP ${response.status}`);
}

const session = (await response.json()) as { checkout_url: string };
console.log(session.checkout_url);

request.json

{
  "amount": "49.95",
  "currency": "USD",
  "external_order_id": "order_1001",
  "description": "Order 1001",
  "success_url": "https://checkout.example.com/orders/order_1001/success",
  "cancel_url": "https://checkout.example.com/orders/order_1001/cart",
  "allowed_origins": ["https://checkout.example.com"]
}

response.json

{
  "allowed_origins": ["https://checkout.example.com"],
  "amount": "49.95",
  "cancel_url": "https://checkout.example.com/orders/order_1001/cart",
  "checkout_session_id": "cs_00000000000000000000000000000000",
  "checkout_url": "https://staging.maxanapay.com/pay/cs_00000000000000000000000000000000",
  "currency": "USD",
  "description": "Order 1001",
  "embed_url": "https://staging.maxanapay.com/embed/cs_00000000000000000000000000000000",
  "environment": "test",
  "expires_at": "2099-01-01T00:30:00+00:00",
  "external_order_id": "order_1001",
  "id": "cs_00000000000000000000000000000000",
  "items": [],
  "merchant_name": "Example Store",
  "metadata": {},
  "payment_provider": "ppcp",
  "shipping_address": null,
  "shipping_amount_cents": null,
  "status": "open",
  "success_url": "https://checkout.example.com/orders/order_1001/success"
}

The response’s environment is the API key’s environment, and the browser example’s environment option is the SDK’s. They are separate vocabularies that share one spelling: a sandbox key creates a session that reads test, while the SDK option for that same deployment is sandbox. Passing one into the other throws config_error before checkout mounts. See Environments.

Before accepting traffic

• Keep all secret keys out of browser code, logs, analytics, and URLs.
• Use an idempotency key when the operation contract accepts one.
• Store Maxana and provider identifiers with your own order identifier.
• Exercise success, decline, cancellation, timeout, duplicate webhook, and delayed webhook paths in sandbox.

Current limits

The browser SDK currently mounts the PayPal wallet rail and excludes the capabilities listed in the SDK reference. Use Hosted Checkout or Embedded Checkout when the session needs one of those capabilities, and do not treat sandbox credentials or state as live-ready.