Connect checkout to an order

Keep the store order and the Moneybag payment transaction as separate records. Your backend creates checkout, records its session against the order, and makes the fulfillment decision only after server-side verification.

1. Freeze the payable order

Calculate the order total in your trusted backend and assign a unique order_id. Do not accept a total calculated by the browser or reuse an identifier from a previous checkout attempt.

2. Create hosted checkout

POST/api/v2/payments/checkout

Send the reviewed checkout schema with X-Merchant-API-Key from your backend.

Persist the returned session_id with the order and redirect the customer to the exact returned checkout_url. Do not construct the hosted URL yourself.

3. Treat the return as navigation

Success, failure, and cancellation URLs determine where the customer returns; they do not authorize fulfillment. Show a pending result while your backend verifies the transaction when the outcome is not yet authoritative.

4. Verify and fulfill once

GET/api/v2/payments/verify/{transaction_id}

Confirm the expected order, amount, currency, and terminal state server-side.

Claim the order in a database transaction before applying inventory, delivery, or entitlement changes. Repeated redirects, verification calls, and webhook deliveries must not repeat fulfillment.

5. Reconcile asynchronous events

Validate webhook signatures over the raw body, record the event ID before processing, and re-fetch authoritative state when an event conflicts with your order. See Webhooks for the signing boundary.

This guide intentionally does not claim support for a named commerce platform, saved payment methods, refunds, inventory automation, or a PCI scope. Use the SDK and library guidance before adopting a third-party package.