Getting started

Integrate from your backend with a test API key. Create checkout sessions through the staging API, then receive signed status updates at your webhook endpoint.

Before you begin

Prepare these integration details:

• A test merchant organization
• A test API key with the mb_test_ prefix
• A public HTTPS endpoint for webhook deliveries
• Server-side storage for API keys, webhook secrets, and idempotency keys

Never place API keys or webhook secrets in browser or mobile application code.

Create a checkout session

Create checkout sessions from your backend at the staging base URL. Amount fields use integer minor units, so 2500 represents USD 25.00.

1. Save an idempotency key

Generate a UUID before the first request and save it with your order. Reuse that value only when retrying the same request.

const idempotencyKey = crypto.randomUUID();

The idempotency guide explains retry and conflict behavior.

2. Build the checkout request

This payload creates one hosted checkout session for USD 25.00.

const checkout = {
  currency: "USD",
  amount: 2500,
  amount_subtotal: 2500,
  amount_total: 2500,
  success_url: "https://merchant.example/checkout/success",
  cancel_url: "https://merchant.example/cart",
  line_items: [{
    quantity: 1,
    amount_subtotal: 2500,
    price_data: {
      currency: "USD",
      unit_amount: 2500,
      product_data: { name: "Example order" },
    },
  }],
};

See Create a checkout session for every supported field.

3. Send the request from your backend

Send the API key and saved idempotency key in request headers.

const response = await fetch(
  "https://stg-checkout-api.mbwallet.dev/v1/checkout_sessions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MB_WALLET_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify(checkout),
  },
);

if (!response.ok) throw new Error(await response.text());
const session = await response.json();

Store the returned session id with your order. Use it to retrieve or cancel that checkout session.

4. Continue to the checkout experience

Store the returned MB-PAYMENT-… session identifier. Use the checkout launch flow supplied during private-preview onboarding.

5. Receive the final status

Use webhooks as the source of asynchronous status changes. You may also retrieve the session by its MB-PAYMENT-… identifier when reconciling state.

Prepare webhook delivery

Register a test-mode endpoint in the MB Wallet Merchant Console. Store the returned mbsec_ signing secret, then implement the webhook verification flow.

Do not mark an order paid from the shopper's redirect alone. Confirm the captured state from a verified webhook or a server-side API read.