EMI API

EMI Payment Integration

Overview

Merchants can integrate EMI payments in two ways:

Pre-calculated EMI - Get EMI options first, then checkout with specific configuration
Checkout EMI Selection - Let customer choose EMI during payment with requires_emi: true

Integration Flow Diagram

Minimum Order Value

EMI is only available for orders with a minimum amount of ৳3,000 BDT. Orders below this threshold cannot use EMI payment.

Method 1: Pre-calculated EMI Checkout

Use this method when you want to show EMI options before checkout and let customers select a specific plan.

Step 1: Get Available EMI Options (Optional)

Fetch all available EMI banks and tenures to display on your site.

curl https://sandbox.api.moneybag.com.bd/api/v2/payments/emi-options \
  --header 'X-Merchant-API-Key: your_merchant_api_key'

Step 2: Calculate EMI Breakdown

Calculate EMI amounts for a specific order. You can either:

Show all options: Omit emi_configuration_id to get calculations for all available EMI plans
Show specific options: Provide emi_configuration_id array to filter specific plans

Option A: Get all available EMI calculations

curl https://sandbox.api.moneybag.com.bd/api/v2/payments/emi-amounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Merchant-API-Key: your_merchant_api_key' \
  --data '{
    "order_amount": "10000.00"
  }'

Option B: Get specific EMI calculations

curl https://sandbox.api.moneybag.com.bd/api/v2/payments/emi-amounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Merchant-API-Key: your_merchant_api_key' \
  --data '{
    "order_amount": "10000.00",
    "emi_configuration_id": ["emib16e7ca033ea42fe834653d513d475a5"]
  }'

Step 3: Checkout with Selected EMI

After customer selects their preferred EMI plan, create checkout with the selected configuration.

curl https://sandbox.api.moneybag.com.bd/api/v2/payments/checkout \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Merchant-API-Key: your_merchant_api_key' \
  --data '{
    "order_id": "INV-10125441238360",
    "currency": "BDT",
    "order_amount": "10000.00",
    "order_description": "Online purchase of electronics",
    "success_url": "https://example.com/payment/success",
    "cancel_url": "https://example.com/payment/cancel",
    "fail_url": "https://example.com/payment/fail",
    "customer": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "address": "123 Main Street",
      "city": "Dhaka",
      "postcode": "1000",
      "country": "Bangladesh",
      "phone": "+8801700000000"
    },
    "payment_info": {
      "requires_emi": true,
      "emi_configuration_id": "emib16e7ca033ea42fe834653d513d475a5"
    }
  }'

Method 2: Checkout EMI Selection

Use this method to let customers choose EMI options during the payment process on Moneybag's payment page.

Checkout with EMI Enabled

curl https://sandbox.api.moneybag.com.bd/api/v2/payments/checkout \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Merchant-API-Key: your_merchant_api_key' \
  --data '{
    "order_id": "INV-10125441238360",
    "currency": "BDT",
    "order_amount": "10000.00",
    "order_description": "Online purchase of electronics",
    "success_url": "https://example.com/payment/success",
    "cancel_url": "https://example.com/payment/cancel",
    "fail_url": "https://example.com/payment/fail",
    "customer": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "address": "123 Main Street",
      "city": "Dhaka",
      "postcode": "1000",
      "country": "Bangladesh",
      "phone": "+8801700000000"
    },
    "payment_info": {
      "requires_emi": true
    }
  }'

Payment Info Parameters for EMI

Field	Type	Required	Description
requires_emi	boolean	Yes	Set to `true` to enable EMI payment
emi_configuration_id	string	No	Specific EMI configuration UUID. If not provided, customer can choose from all available options
payment_service_id	integer	No	Payment service identifier (optional)
currency_conversion	boolean	No	Whether currency conversion is required (default: false)

Comparison: Pre-calculated vs Checkout EMI Selection

Feature	Pre-calculated EMI	Checkout EMI Selection
Control	Full control over EMI options shown	Customer chooses on payment page
UX	Display EMI breakdown on your site	Simpler integration
API Calls	2-3 calls (options → calculate → checkout)	1 call (checkout only)
Use Case	Product pages, marketing campaigns	Quick checkout, minimal setup
Complexity	Higher	Lower

EMI Validation Rules

Minimum Order Amount: ৳3,000 BDT
Maximum Order Amount: Based on bank and tenure configuration
Valid Currency: BDT only
Customer Info: All customer fields must be provided
EMI Configuration: Must be active and valid

Error Response for Invalid Amount

{
  "success": false,
  "error": {
    "code": "INVALID_EMI_AMOUNT",
    "message": "Order amount must be at least 3000.00 BDT to use EMI",
    "field": "order_amount"
  }
}

Endpoint Details

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>

API Reference

Get Available EMI Options

Get available EMI options for a specific merchant. This is a customer-facing API that returns all configured EMI plans.

Endpoint

GET /payments/emi-options

Headers

Header	Value	Required
X-Merchant-API-Key	Your merchant API key	Yes

Response

HTTP Status: 200 OK

{
  "success": true,
  "message": "EMI options retrieved successfully",
  "data": {
    "emi_options": [
      {
        "bank_name": "FlexiPay Financial",
        "tenures": [
          {
            "interest_rate": "12.00",
            "tenure": "3",
            "uuid": "f336d0bc-b841-465b-8045-024475c079dd"
          },
          {
            "interest_rate": "14.00",
            "tenure": "6",
            "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          }
        ]
      },
      {
        "bank_name": "QuickEMI Bank",
        "tenures": [
          {
            "interest_rate": "10.00",
            "tenure": "3",
            "uuid": "11111111-2222-3333-4444-555555555555"
          }
        ]
      }
    ]
  },
  "meta": {}
}

Response Fields

Field	Type	Description
emi_options	array	List of available EMI options grouped by bank
bank_name	string	Name of the bank offering EMI
tenures	array	Available tenure options for the bank
interest_rate	string	Interest rate percentage for the tenure
tenure	string	EMI tenure in months (e.g., "3", "6", "12")
uuid	string	Unique identifier for the EMI configuration

Example Request

curl https://sandbox.api.moneybag.com.bd/api/v2/payments/emi-options \
  --header 'X-Merchant-API-Key: your_merchant_api_key'

Calculate EMI Options with Charges

Calculate available EMI options with complete charge breakdown for a given order amount.

Flexible Filtering

If emi_configuration_id is not provided, the API returns calculations for all available EMI options configured for your merchant account.

Endpoint

POST /payments/emi-amounts

Headers

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

Request Body

{
  "order_amount": "12000.00",
  "emi_configuration_id": [
    "f336d0bc-b841-465b-8045-024475c079dd"
  ]
}

Request Parameters

Field	Type	Required	Description
order_amount	string/number	Yes	The total order amount for EMI calculation
emi_configuration_id	array	No	Optional list of EMI configuration UUIDs to filter. If not provided, all eligible configurations will be returned

Response

HTTP Status: 200 OK

{
  "success": true,
  "message": "EMI amounts calculated successfully",
  "data": {
    "order_amount": "12000.00",
    "merchant_bleeding": true,
    "emi_payment_options": [
      {
        "bank_name": "FlexiPay Financial",
        "tenure": "3",
        "interest_rate": "12.00",
        "monthly_installment": "4048.00",
        "total_amount": "12144.00",
        "total_interest": "144.00",
        "processing_fee": "120.00",
        "uuid": "f336d0bc-b841-465b-8045-024475c079dd"
      },
      {
        "bank_name": "FlexiPay Financial",
        "tenure": "6",
        "interest_rate": "14.00",
        "monthly_installment": "2086.67",
        "total_amount": "12520.00",
        "total_interest": "520.00",
        "processing_fee": "120.00",
        "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    ]
  },
  "meta": {}
}

Response Fields

Field	Type	Description
order_amount	string	The original order amount
merchant_bleeding	boolean	Indicates if merchant absorbs EMI costs
emi_payment_options	array	List of calculated EMI options
bank_name	string	Name of the bank
tenure	string	EMI tenure in months
interest_rate	string	Interest rate percentage
monthly_installment	string	Amount to be paid monthly
total_amount	string	Total amount to be paid including interest
total_interest	string	Total interest amount
processing_fee	string	One-time processing fee
uuid	string	EMI configuration UUID

Example Request

curl https://sandbox.api.moneybag.com.bd/api/v2/payments/emi-amounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Merchant-API-Key: your_merchant_api_key' \
  --data '{
    "order_amount": "12000.00",
    "emi_configuration_id": [
      "f336d0bc-b841-465b-8045-024475c079dd"
    ]
  }'

Error Response

HTTP Status: 422 Validation Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "order_amount",
        "message": "Order amount must be a positive number"
      }
    ]
  }
}

Use Cases

1. Display EMI Options on Product Page

Fetch available EMI options to display on your product or checkout page:

Call GET /payments/emi-options to get all available banks and tenures
Display options like "Pay in 3 months at 12% interest"
Show which banks offer EMI

2. Calculate Exact EMI Breakdown

Calculate detailed EMI breakdown when customer selects an option:

User selects product worth ₹12,000
Call POST /payments/emi-amounts with order amount
Display monthly installment, total amount, and interest
Customer can compare different tenure options

3. Filter Specific EMI Plans

Show only specific EMI configurations:

Pass emi_configuration_id array with desired UUIDs
Useful when you want to promote specific bank partnerships
Filter by tenure or interest rates

Integration Flow

Fetch Available Options - Call GET /payments/emi-options to get all EMI configurations
Display to Customer - Show available banks and tenures on your product/checkout page
Calculate Charges - When customer selects amount, call POST /payments/emi-amounts for exact breakdown
Show Breakdown - Display monthly installment, total amount, and interest to customer
Proceed to Checkout - Use the selected uuid in your checkout request with EMI enabled

Best Practices

Cache EMI options response for better performance (update daily)
Always show complete breakdown including interest and fees
Display total amount clearly alongside monthly installment
Provide EMI calculator tool for customers to explore options
Update EMI options when merchant configurations change

Checkout API - Use EMI with checkout
Webhooks - EMI payment notifications

Minimum Order Value

Flexible Filtering

On this page