Your first sandbox payment

Create a checkout from a trusted backend, send the customer through hosted checkout, and verify the transaction before you update an order.

Before you begin

You need a sandbox merchant and its one-time merchant API key. Store that key in your server-side secret manager. Do not place it in frontend JavaScript, mobile application code, URLs, analytics, logs, screenshots, or AI prompts.

If you do not have a sandbox merchant, create one. After provisioning, the platform connects the API Lab through an encrypted HttpOnly workspace session.

1. Create the checkout on your server

The backend currently exposes the checkout operation below. It authenticates with the merchant key and creates a merchant-scoped payment session.

POST/api/v2/payments/checkout

Send the merchant key in the X-Merchant-API-Key header.

curl --request POST "$MONEYBAG_BASE_URL/api/v2/payments/checkout" \
  --header "Content-Type: application/json" \
  --header "X-Merchant-API-Key: $MONEYBAG_MERCHANT_KEY" \
  --data '{
    "order_id": "ORDER-1001",
    "order_amount": "1280.00",
    "currency": "BDT",
    "order_description": "Sandbox order",
    "success_url": "https://merchant.example/payments/success",
    "cancel_url": "https://merchant.example/payments/cancel",
    "fail_url": "https://merchant.example/payments/failure",
    "ipn_url": "https://merchant.example/webhooks/moneybag",
    "customer": {
      "name": "Sandbox Customer",
      "email": "sandbox.customer@example.com",
      "phone": "+8801700000000",
      "address": "Dhaka",
      "city": "Dhaka",
      "postcode": "1000",
      "country": "Bangladesh"
    }
  }'

Treat the returned checkout_url, session_id, and expires_at as transient checkout state. Associate the session with your internal order.

2. Redirect the customer

Redirect the customer to the exact checkout_url returned by Moneybag. Do not construct a hosted-checkout URL yourself and do not expose the merchant key.

3. Complete a sandbox outcome

Choose success, failure, or cancellation in hosted sandbox checkout, or use the reviewed simulator actions in the API Lab. Simulation authorization stays behind the platform BFF and is never sent to page scripts.

4. Verify from your backend

Customer redirects are navigation signals, not proof of payment. Read the transaction identifier returned by the supported flow and verify it from your trusted backend.

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

Send the merchant key in the X-Merchant-API-Key header.

curl "$MONEYBAG_BASE_URL/api/v2/payments/verify/$TRANSACTION_ID" \
  --header "X-Merchant-API-Key: $MONEYBAG_MERCHANT_KEY"

Update your order only from a verified terminal state. Make the update idempotent so repeated redirects, verification calls, or webhook deliveries do not fulfill the same order twice.

5. Reconcile the webhook

Treat the webhook and explicit verification as complementary signals. Validate the webhook signature using the verified signing contract, persist its event identity, reject cross-merchant data, and process duplicate deliveries safely.