Hosted payments

Create a checkout

Create checkout from your backend, then redirect the customer to Moneybag's hosted payment experience.

Generate and persist a unique order_id before calling Moneybag. The reference below is rendered from the reviewed public artifact, including nested customer, shipping, line-item, metadata, and EMI fields.

Do not fulfill from the customer redirect. Continue with payment verification.

Collection Dashboard attribution

Add the optional, top-level checkout_source field to identify where a payment originates. The values are case-sensitive:

• WEBSITE_CHECKOUT → Website Checkout: a customer starts checkout on your website, and your backend creates the session.
• API_INTEGRATION → API Integration: your application or automated integration workflow initiates checkout, such as a backend billing workflow.

Any other value, including different casing, causes a request validation error. Omit the field if you are unsure which source applies.

All checkout requests still come from your backend. Choose the value for the payment's origin; calling the checkout API does not automatically make a website payment an API Integration payment.

For a native mobile app that starts checkout through your backend, use API_INTEGRATION. If a WebView loads your merchant website and the customer starts checkout there, use WEBSITE_CHECKOUT. Opening Moneybag's hosted payment page in a WebView does not change the original source.

The API Lab checkout preset includes API_INTEGRATION. When adapting it for website payments, change that value to WEBSITE_CHECKOUT; you can also omit the field to keep checkout unclassified.

For example, a website checkout request can include:

{
  "order_id": "ORDER-WEBSITE-10001",
  "currency": "BDT",
  "order_amount": "100.00",
  "order_description": "Website order",
  "checkout_source": "WEBSITE_CHECKOUT",
  "success_url": "https://merchant.example/payments/success",
  "cancel_url": "https://merchant.example/payments/cancel",
  "fail_url": "https://merchant.example/payments/failure",
  "customer": {
    "name": "Sandbox Customer",
    "email": "sandbox@example.com",
    "phone": "+8801700000000"
  }
}

Send checkout_source alongside order_id, not inside metadata. Metadata such as source or platform does not set the dashboard channel.

Existing integrations can omit the field or send null. These payments appear as Unclassified Checkout; their payment method and successful collection amount are still recorded. Adding the field attributes newly created sessions. Older transactions are not relabeled, and a reused session retains its original channel through retries and redirects.

API reference

curl --request POST "https://sandbox.api.moneybag.com.bd/api/v2/payments/checkout" \
  --header "X-Merchant-API-Key: $MONEYBAG_MERCHANT_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "cancel_url": "https://merchant.example/cancel-url",
    "currency": "BDT",
    "customer": {
      "email": "sandbox.customer@example.com",
      "name": "Sandbox example",
      "phone": "+8801700000000"
    },
    "fail_url": "https://merchant.example/fail-url",
    "order_amount": 100,
    "order_description": "Sandbox API example",
    "order_id": "ORDER-1001",
    "success_url": "https://merchant.example/success-url"
  }'