Create a checkout

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

POST/api/v2/payments/checkout

Create a merchant-scoped sandbox checkout.

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.

Rendering diagram…

The merchant backend creates and verifies checkout. The browser only follows hosted redirects and never receives the merchant API key.

Text alternative

The merchant backend creates and verifies checkout. The browser only follows hosted redirects and never receives the merchant API key.

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

API reference

POST/api/v2/payments/checkout

Checkout

Checkout API This endpoint initiates the payment process for a merchant order. It creates a payment session, processes the initial payment request, and returns a redirect URL to the payment gateway. The merchant must provide a valid API key in the X-Merchant-API-Key header. Args: order_req: Order request data merchant_key: Merchant API key info Returns: CheckoutResponse: Response with checkout details and redirect URL Raises: HTTPException: For any validation or processing errors

Operation ID: checkout_api_v2_payments_checkout_post
Environment: https://sandbox.api.moneybag.com.bd (Moneybag sandbox)
Authentication: X-Merchant-API-Key — Sandbox merchant API key. Live keys are rejected.

Parameters

No path or query parameters.

Request body

Required application/json body using OrderRequest.

Field	Type	Required	Constraints and meaning
`cancel_url`	`string`	Yes	maximum length 255 Callback URL if user cancels the transaction
`currency`	`string`	Yes	— Three-letter currency code (e.g., BDT, USD, EUR)
`customer`	`Customer`	Yes	—
`customer.address`	`string \| null`	No	— Customer's address
`customer.city`	`string \| null`	No	— Customer's city
`customer.country`	`string \| null`	No	— Customer's country
`customer.email`	`string`	Yes	format email Customer's email address
`customer.metadata`	`object \| null`	No	— Additional customer-specific data
`customer.name`	`string`	Yes	— Customer's full name
`customer.phone`	`string`	Yes	— Customer's phone number
`customer.postcode`	`string \| null`	No	— Customer's postal code
`fail_url`	`string`	Yes	maximum length 255 Callback URL if payment failure occurs
`ipn_url`	`string \| null`	No	— Instant Payment Notification URL
`metadata`	`object \| null`	No	— Additional order-specific data
`order_amount`	`number \| string`	Yes	pattern ^(?!^[-+.]$)[+-]?0\d\.?\d$ Transaction amount between 10.00 and 1000000.00 BDT
`order_description`	`string`	Yes	maximum length 255 Description of the order
`order_id`	`string`	Yes	minimum length 10; maximum length 36 Unique transaction ID to identify your order
`order_items`	`OrderItem[] \| null`	No	— List of items in the order
`order_items[].convenience_fee`	`number \| string \| null`	No	pattern ^(?!^[-+.]$)[+-]?0\d\.?\d$ Convenience fee (decimal value)
`order_items[].discount_amount`	`number \| string \| null`	No	pattern ^(?!^[-+.]$)[+-]?0\d\.?\d$ Discount amount (decimal value)
`order_items[].metadata`	`object \| null`	No	— Additional product-specific data
`order_items[].net_amount`	`number \| string \| null`	No	pattern ^(?!^[-+.]$)[+-]?0\d\.?\d$ Net amount after adding VAT and fees, subtracting discounts
`order_items[].product_category`	`string \| null`	No	maximum length 100 Product category (e.g., Electronic, topup)
`order_items[].product_name`	`string \| null`	No	maximum length 255 Product name
`order_items[].quantity`	`integer \| null`	No	— Product quantity
`order_items[].sku`	`string \| null`	No	— Product SKU
`order_items[].unit_price`	`number \| string \| null`	No	pattern ^(?!^[-+.]$)[+-]?0\d\.?\d$ Unit price of the product
`order_items[].vat`	`number \| string \| null`	No	pattern ^(?!^[-+.]$)[+-]?0\d\.?\d$ VAT amount (decimal value)
`payment_info`	`PaymentInfo \| null`	No	— Payment-related information
`payment_info.currency_conversion`	`boolean`	No	default false Whether currency conversion is applied
`payment_info.emi_configuration_id`	`string \| null`	No	— Selected EMI configuration ID (if customer selected specific EMI option)
`payment_info.emi_payment_id`	`integer \| string \| null`	No	— Selected merchant payment service for EMI payment. Accepts the public UUID or, during the migration window, the legacy integer service id.
`payment_info.requires_emi`	`boolean`	No	default false Whether EMI payment options should be shown
`shipping`	`Shipping \| null`	No	— Shipping information
`shipping.address`	`string`	When parent is present	— Shipping address line 1
`shipping.city`	`string`	When parent is present	— Shipping city
`shipping.country`	`string`	When parent is present	— Shipping country
`shipping.metadata`	`object \| null`	No	— Additional shipping-specific data
`shipping.name`	`string`	When parent is present	— Shipping recipient's full name
`shipping.postcode`	`string`	When parent is present	— Shipping postal code
`shipping.state`	`string \| null`	No	— Shipping state/province
`success_url`	`string`	Yes	maximum length 255 Callback URL after successful payment

Sandbox example

Set the merchant key and replace resource identifiers with values created in your sandbox workspace.

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://example.com/payment/cancel",
    "currency": "BDT",
    "customer": {
      "address": "123 Main Street",
      "city": "Dhaka",
      "country": "Bangladesh",
      "email": "john.doe@example.com",
      "metadata": {
        "customer_id": "CUST12345",
        "loyalty_level": "gold"
      },
      "name": "John Doe",
      "phone": "+8801700000000",
      "postcode": "1000"
    },
    "fail_url": "https://example.com/payment/fail",
    "ipn_url": "https://example.com/payment/ipn",
    "metadata": {
      "ip_address": "192.168.1.1",
      "platform": "web",
      "session_id": "SESSION12345",
      "source": "web",
      "user_agent": "Mozilla/5.0"
    },
    "order_amount": "1280.00",
    "order_description": "Online purchase of electronics",
    "order_id": "TXN12345678",
    "order_items": [
      {
        "convenience_fee": "80.00",
        "discount_amount": "100.00",
        "net_amount": "1300.00",
        "product_category": "Electronic",
        "product_name": "iPhone 15",
        "quantity": 1,
        "sku": "PROD001",
        "unit_price": "1200.00",
        "vat": "120.00"
      },
      {
        "convenience_fee": "0",
        "discount_amount": "0",
        "net_amount": "1650.00",
        "product_category": "Electronic",
        "product_name": "iPhone 15 Pro",
        "quantity": 1,
        "sku": "PROD002",
        "unit_price": "1500.00",
        "vat": "150.00"
      }
    ],
    "payment_info": {
      "currency_conversion": false,
      "requires_emi": false
    },
    "shipping": {
      "address": "123 Main Street",
      "city": "Dhaka",
      "country": "Bangladesh",
      "name": "John Doe",
      "postcode": "1000"
    },
    "success_url": "https://example.com/payment/success"
  }'

Run this reviewed operation in the API Lab →

Responses

`200` Successful Response

Content type: application/json. Schema: PaymentResponses.

Field	Type	Required	Constraints and meaning
`data`	`CheckoutResponse \| SessionResponse \| ProcessResponse \| VerificationResponse \| InvoiceDetailsResponse \| CancelResponse \| CheckoutResponse \| SessionResponse \| ProcessResponse \| VerificationResponse \| InvoiceDetailsResponse \| CancelResponse[] \| null`	No	—
`data<CheckoutResponse>.checkout_url`	`string`	When parent is present	—
`data<CheckoutResponse>.expires_at`	`string`	When parent is present	—
`data<CheckoutResponse>.session_id`	`string`	When parent is present	—
`data<SessionResponse>.bleeding`	`boolean`	No	default false Whether merchant pays service charges (bleeding)
`data<SessionResponse>.business_name`	`string \| null`	No	—
`data<SessionResponse>.currency`	`string`	When parent is present	—
`data<SessionResponse>.customer`	`object \| null`	No	—
`data<SessionResponse>.emi_checkout_id`	`string \| null`	No	— Selected EMI configuration UUID if pre-selected
`data<SessionResponse>.emi_fee_bleeding`	`boolean`	No	default false Whether merchant pays EMI fees (emi_fee_bleeding)
`data<SessionResponse>.emi_payment_options`	`object[] \| null`	No	— EMI payment options with calculations
`data<SessionResponse>.expires_at`	`string`	When parent is present	—
`data<SessionResponse>.merchant_logo`	`string \| null`	No	—
`data<SessionResponse>.order_amount`	`string`	When parent is present	pattern ^(?!^[-+.]$)[+-]?0\d\.?\d$
`data<SessionResponse>.order_description`	`string \| null`	No	—
`data<SessionResponse>.order_id`	`string`	When parent is present	—
`data<SessionResponse>.payment_options`	`object[]`	When parent is present	—
`data<SessionResponse>.requires_emi`	`boolean`	No	default false Whether EMI payment options are available
`data<SessionResponse>.selected_emi_configuration`	`SelectedEMIConfiguration \| null`	No	— Selected EMI configuration with emi_configuration_id, service_id and service_uuid
`data<SessionResponse>.selected_emi_configuration.emi_configuration_id`	`string`	When parent is present	— Selected EMI configuration ID
`data<SessionResponse>.selected_emi_configuration.payment_service_id`	`integer \| string \| null`	No	— Deprecated alias of service_id, kept for backward compatibility
`data<SessionResponse>.selected_emi_configuration.service_id`	`integer \| null`	No	— Internal merchant payment service id, matches payment_options[].service_id
`data<SessionResponse>.selected_emi_configuration.service_uuid`	`string \| null`	No	— Public merchant payment service UUID, matches payment_options[].service_uuid
`data<SessionResponse>.session_id`	`string`	When parent is present	—
`data<SessionResponse>.status`	`string`	When parent is present	—
`data<ProcessResponse>.meta`	`object \| null`	No	—
`data<ProcessResponse>.redirect_url`	`string \| null`	No	format uri; minimum length 1
`data<ProcessResponse>.transaction_id`	`string`	When parent is present	—
`data<VerificationResponse>.amount`	`string`	When parent is present	pattern ^(?!^[-+.]$)[+-]?0\d\.?\d$
`data<VerificationResponse>.charge_amount`	`string`	When parent is present	pattern ^(?!^[-+.]$)[+-]?0\d\.?\d$
`data<VerificationResponse>.currency`	`string`	When parent is present	—
`data<VerificationResponse>.customer`	`Customer`	When parent is present	—
`data<VerificationResponse>.customer.address`	`string \| null`	No	— Customer's address
`data<VerificationResponse>.customer.city`	`string \| null`	No	— Customer's city
`data<VerificationResponse>.customer.country`	`string \| null`	No	— Customer's country
`data<VerificationResponse>.customer.email`	`string`	When parent is present	format email Customer's email address
`data<VerificationResponse>.customer.metadata`	`object \| null`	No	— Additional customer-specific data
`data<VerificationResponse>.customer.name`	`string`	When parent is present	— Customer's full name
`data<VerificationResponse>.customer.phone`	`string`	When parent is present	— Customer's phone number
`data<VerificationResponse>.customer.postcode`	`string \| null`	No	— Customer's postal code
`data<VerificationResponse>.order_id`	`string`	When parent is present	—
`data<VerificationResponse>.payment_method`	`string`	When parent is present	—
`data<VerificationResponse>.payment_reference_id`	`string`	When parent is present	—
`data<VerificationResponse>.status`	`string`	When parent is present	—
`data<VerificationResponse>.transaction_id`	`string`	When parent is present	—
`data<VerificationResponse>.verified`	`boolean`	When parent is present	—
`data<InvoiceDetailsResponse>.all_total`	`number`	When parent is present	—
`data<InvoiceDetailsResponse>.business_name`	`string`	When parent is present	—
`data<InvoiceDetailsResponse>.customer`	`object \| null`	When parent is present	—
`data<InvoiceDetailsResponse>.due_date`	`string \| null`	When parent is present	—
`data<InvoiceDetailsResponse>.gross_discount`	`number`	When parent is present	—
`data<InvoiceDetailsResponse>.invoice_id`	`string`	When parent is present	—
`data<InvoiceDetailsResponse>.invoice_items`	`object[]`	When parent is present	—
`data<InvoiceDetailsResponse>.invoice_status`	`string`	When parent is present	—
`data<InvoiceDetailsResponse>.invoice_type`	`string \| null`	No	—
`data<InvoiceDetailsResponse>.merchant_logo`	`string \| null`	No	—
`data<InvoiceDetailsResponse>.payable_amount`	`number`	When parent is present	—
`data<InvoiceDetailsResponse>.uuid`	`string`	When parent is present	—
`data<CancelResponse>.order_id`	`string`	When parent is present	—
`data<CancelResponse>.redirect_url`	`string`	When parent is present	—
`data<CancelResponse>.session_id`	`string`	When parent is present	—
`data<CancelResponse>.status`	`string`	No	default "CANCELLED"
`message`	`string \| null`	No	—
`meta`	`object \| null`	No	—
`success`	`boolean`	Yes	—

`422` Validation Error

Content type: application/json. Schema: HTTPValidationError.

Field	Type	Required	Constraints and meaning
`detail`	`ValidationError[]`	No	—
`detail[].loc`	`string \| integer[]`	When parent is present	—
`detail[].msg`	`string`	When parent is present	—
`detail[].type`	`string`	When parent is present	—

OpenAPI 2.0.0 · operation checkout_api_v2_payments_checkout_post · contract digest cd0bbb4532452feec6b880fcc3d9190688618f7bcba1987cf518bc9107799cfe