Checkout API

The Checkout endpoint initiates a payment session for a customer order and returns a checkout URL where the customer can complete the payment.

Endpoint Details

Endpoint: POST /payments/checkout

Base URLs:

Sandbox: https://sandbox.api.moneybag.com.bd/api/v2
Production: https://api.moneybag.com.bd/api/v2

Authentication

All requests require authentication via API key in the header:

X-Merchant-API-Key: <your_merchant_api_key>

Request

Headers

Header	Value	Required
X-Merchant-API-Key	Your merchant API key	Yes
Content-Type	application/json	Yes

Request Body

{
  "order_id": "order123321",
  "currency": "BDT",
  "order_amount": "1280.00",
  "order_description": "Online purchase of electronics",
  "success_url": "https://yourdomain.com/payment/success",
  "cancel_url": "https://yourdomain.com/payment/cancel",
  "fail_url": "https://yourdomain.com/payment/fail",
  "ipn_url": "https://yourdomain.com/payment/ipn",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "address": "123 Main Street",
    "city": "Dhaka",
    "postcode": "1000",
    "country": "Bangladesh",
    "phone": "+8801700000000"
  },
  "order_items": [
    {
      "sku": "PROD001",
      "net_amount": "1300.00"
    }
  ],
  "shipping": {
    "name": "John Doe",
    "address": "123 Main Street",
    "city": "Dhaka",
    "postcode": "1000",
    "country": "Bangladesh"
  },
  "metadata": {
    "source": "web",
    "session_id": "SESSION12345",
    "user_agent": "Mozilla/5.0",
    "ip_address": "192.168.1.1",
    "platform": "web"
  },
  "payment_info": {
    "is_recurring": false,
    "installments": 0,
    "currency_conversion": false,
    "allowed_payment_methods": ["card", "mobile_banking"],
    "requires_emi": false
  }
}

Request Parameters

Root Level Fields

Field	Type	Required	Description	Constraints
order_id	string	Yes	Unique transaction ID to identify your order	Max 30 chars
currency	string	Yes	Three-letter currency code	Must match `^[A-Z]{3}$`
order_amount	decimal	Yes	Transaction amount	Between 10.00 and 500000.00 BDT
order_description	string	No	Description of the order
success_url	string	Yes	Callback URL after successful payment	Max 255 chars, must be HTTPS
cancel_url	string	Yes	Callback URL if user cancels	Max 255 chars, must be HTTPS
fail_url	string	Yes	Callback URL if payment fails	Max 255 chars, must be HTTPS
ipn_url	string	No	Instant Payment Notification URL	Must be HTTPS
customer	object	Yes	Customer information	See Customer Object
shipping	object	No	Shipping information	See Shipping Object
order_items	array	No	List of items in the order	See OrderItem Object
payment_info	object	No	Payment-related information	See PaymentInfo Object
metadata	object	No	Additional order-specific data

Customer Object

Field	Type	Required	Description
name	string	Yes	Customer full name
email	string	Yes	Customer email address
address	string	Yes	Customer address
city	string	Yes	Customer city
postcode	string	Yes	Customer postal code
country	string	Yes	Customer country
phone	string	Yes	Customer phone number

Shipping Object

Field	Type	Required	Description
name	string	Yes	Recipient's full name
address	string	Yes	Shipping address
city	string	Yes	Shipping city
state	string	No	Shipping state/province
postcode	string	Yes	Shipping postal code
country	string	Yes	Shipping country
metadata	object	No	Additional shipping data

OrderItem Object

Field	Type	Required	Description
sku	string	No	Product SKU
product_name	string	No	Product name
product_category	string	No	Product category
quantity	integer	No	Product quantity
unit_price	decimal	No	Unit price of the product
vat	decimal	No	VAT amount
convenience_fee	decimal	No	Convenience fee
discount_amount	decimal	No	Discount amount
net_amount	decimal	No	Net amount after calculations
metadata	object	No	Additional product data

PaymentInfo Object

Field	Type	Required	Description
is_recurring	boolean	No	Whether this is a recurring payment
installments	integer	No	Number of installments if applicable
currency_conversion	boolean	No	Whether currency conversion is applied
allowed_payment_methods	array	Yes	List of allowed payment methods
requires_emi	boolean	No	Whether EMI is required

Response

Success Response

HTTP Status: 200 OK

{
  "success": true,
  "data": {
    "checkout_url": "https://payment.moneybag.com.bd/moneybag-landing?sessionId=ps1234567890",
    "session_id": "ps1234567890",
    "expires_at": "2025-05-19T15:00:00Z"
  },
  "message": "Checkout session created"
}

Response Fields

Field	Type	Description
checkout_url	string	URL to redirect customer for payment
session_id	string	Unique session ID for the payment
expires_at	datetime	Expiry date/time of the session (ISO format)

Error Response

HTTP Status: 400/401/403/500

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The order_amount must be between 10.00 and 500000.00",
    "field": "order_amount"
  }
}

Code Examples

cURL

curl -X POST \
  "https://sandbox.api.moneybag.com.bd/api/v2/payments/checkout" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-API-Key: <your_merchant_api_key>" \
  -d '{
    "order_id": "order123321",
    "currency": "BDT",
    "order_amount": "1280.00",
    "order_description": "Online purchase of electronics",
    "success_url": "https://yourdomain.com/payment/success",
    "cancel_url": "https://yourdomain.com/payment/cancel",
    "fail_url": "https://yourdomain.com/payment/fail",
    "customer": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+8801700000000"
    }
  }'

JavaScript (Node.js)

const axios = require('axios');

async function createCheckout() {
  try {
    const response = await axios.post(
      'https://sandbox.api.moneybag.com.bd/api/v2/payments/checkout',
      {
        order_id: 'order123321',
        currency: 'BDT',
        order_amount: '1280.00',
        order_description: 'Online purchase of electronics',
        success_url: 'https://yourdomain.com/payment/success',
        cancel_url: 'https://yourdomain.com/payment/cancel',
        fail_url: 'https://yourdomain.com/payment/fail',
        customer: {
          name: 'John Doe',
          email: 'john.doe@example.com',
          phone: '+8801700000000'
        }
      },
      {
        headers: {
          'X-Merchant-API-Key': 'your_merchant_api_key',
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Checkout URL:', response.data.data.checkout_url);
    // Redirect customer to checkout_url
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

Python

import requests

def create_checkout():
    url = 'https://sandbox.api.moneybag.com.bd/api/v2/payments/checkout'
    
    headers = {
        'X-Merchant-API-Key': 'your_merchant_api_key',
        'Content-Type': 'application/json'
    }
    
    data = {
        'order_id': 'order123321',
        'currency': 'BDT',
        'order_amount': '1280.00',
        'order_description': 'Online purchase of electronics',
        'success_url': 'https://yourdomain.com/payment/success',
        'cancel_url': 'https://yourdomain.com/payment/cancel',
        'fail_url': 'https://yourdomain.com/payment/fail',
        'customer': {
            'name': 'John Doe',
            'email': 'john.doe@example.com',
            'phone': '+8801700000000'
        }
    }
    
    response = requests.post(url, headers=headers, json=data)
    result = response.json()
    
    if result['success']:
        print(f"Checkout URL: {result['data']['checkout_url']}")
        # Redirect customer to checkout_url
    else:
        print(f"Error: {result['error']['message']}")

PHP

<?php
$curl = curl_init();

$data = [
    'order_id' => 'order123321',
    'currency' => 'BDT',
    'order_amount' => '1280.00',
    'order_description' => 'Online purchase of electronics',
    'success_url' => 'https://yourdomain.com/payment/success',
    'cancel_url' => 'https://yourdomain.com/payment/cancel',
    'fail_url' => 'https://yourdomain.com/payment/fail',
    'customer' => [
        'name' => 'John Doe',
        'email' => 'john.doe@example.com',
        'phone' => '+8801700000000'
    ]
];

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://sandbox.api.moneybag.com.bd/api/v2/payments/checkout',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'X-Merchant-API-Key: your_merchant_api_key',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$result = json_decode($response, true);

if ($result['success']) {
    // Redirect to checkout URL
    header('Location: ' . $result['data']['checkout_url']);
    exit;
}
?>

Try in Playground

Try Out in Playground

Integration Flow

Collect Order Details: Gather order and customer information on your site
Call Checkout API: Send POST request with required data
Get Payment URL: Receive checkout_url in response
Redirect Customer: Send customer to checkout_url
Handle Callback: Process success/fail/cancel callbacks
Verify Payment: Use Verify API to confirm payment

Testing

Use our Sandbox Environment to test your integration:

Test cards for different scenarios
Mobile banking test accounts
Amount-based testing triggers
Webhook testing tools

Common Issues

Invalid Amount Error

Ensure amount is between 10.00 and 500000.00 BDT
Use string format with exactly 2 decimal places

Missing Customer Data

All customer fields are required
Phone must include country code

URL Validation Failed

Use HTTPS for all callback URLs
Ensure URLs are publicly accessible

Verify API - Verify payment status
Webhooks - Real-time notifications
Error Codes - Complete error reference
Authentication - API security guide

Checkout API

On this page