Developer Documentation

Everything you need to integrate iPayBD payments into your application.

Get Started API Reference

Documentation

Overview

🔹 What is iPaybd?
iPayBd is a powerful Instant Automatic Deposit and Withdrawal Solution designed for merchants, small businesses, and platform developers. It enables seamless and automated fund transfers between your application and customer wallets through mobile banking services. With iPayBd, any web application, mobile app, or software platform can effortlessly: ● Accept payments (deposits) from customers via mobile banking. ● Withdraw funds directly to the customer’s mobile wallet. iPayBd is easy to integrate using HTTP-based RESTful APIs and returns data in JSON format, making it developer-friendly and fast to deploy.

  • Instant Payment Collection via: bKash, Nagad, Rocket, Upay and more
  • Automated Withdrawals to customer wallets
  • Real-Time Validation of transaction data
  • JSON API with HTTP request/response
  • Webhook Support for instant transaction notifications

Architecture Overview

Client Side

Secure collection of payment details using our API

Server Side

Payment processing and transaction management via API

Webhooks

Real-time notifications for payment events

Integration Process

1

Account Setup

Create an account and get your API keys

2

Integration

Implement payment flow using our APIs

3

Testing

Test integration using test API keys

4

Go Live

Switch to production API keys and start accepting payments

Getting Started

Follow these steps to start accepting payments with iPayBD.

Base URL

ibotbd.com

1. Get Your API Keys

X-Authorization="pk_test_123..."
X-Authorization-Secret="sk_test_456..."

Create Payment

POST /api/v1/payment/create-payment

HTTP Request Examples

curl -X POST "https://example.com/api/v1/payment/create-payment" \
                    -H "X-Authorization: pk_test_123..." \
                    -H "X-Authorization-Secret: sk_test_456..." \
                    -H "Content-Type: application/json" \
                    -d '{
                        "amount": "1100",
                        "reference": "iuy87dFfJ",
                        "currency": "BDT",
                        "callback_url": "https://example.com",
                        "cust_name": "arif",                    
                        "note": "test"
                    }'
$curl = curl_init();

                    curl_setopt_array($curl, array(
                        CURLOPT_URL => "https://example.com/api/v1/payment/create-payment",
                        CURLOPT_RETURNTRANSFER => true,
                        CURLOPT_HTTPHEADER => array(
                            "X-Authorization: pk_test_123...",
                            "X-Authorization-Secret: sk_test_456...",
                            "Content-Type: application/json"
                        ),
                        CURLOPT_POSTFIELDS => '{
                            "amount": "1100",
                            "reference": "iuy87dFfJ",
                            "currency": "BDT",
                            "callback_url": "https://example.com",
                            "cust_name": "arif",
                            "note": "test"
                        }'
                    ));

                    $response = curl_exec($curl);
                    curl_close($curl);
                    echo $response;
import requests

                    url = "https://example.com/api/v1/payment/create-payment"
                    headers = {
                        "X-Authorization": "pk_test_123...",
                        "X-Authorization-Secret": "sk_test_456...",
                        "Content-Type": "application/json"
                    }
                    payload = {
                        "amount": "1100",
                        "reference": "iuy87dFfJ",
                        "currency": "BDT",
                        "callback_url": "https://example.com",
                        "cust_name": "arif",
                        "note": "test"
                    }

                    response = requests.post(url, json=payload, headers=headers)
                    print(response.json())
const url = "https://example.com/api/v1/payment/create-payment";
                    const headers = {
                        "X-Authorization": "pk_test_123...",
                        "X-Authorization-Secret": "sk_test_456...",
                        "Content-Type": "application/json"
                    };
                    const payload = {
                        amount: "1100",
                        reference: "iuy87dFfJ",
                        currency: "BDT",
                        callback_url: "https://example.com",
                        cust_name: "arif",
                        note: "test"
                    };

                    fetch(url, {
                        method: "POST",
                        headers: headers,
                        body: JSON.stringify(payload)
                    })
                    .then(response => response.json())
                    .then(data => console.log(data))
                    .catch(error => console.error(error));
using System;
                    using System.Net.Http;
                    using System.Text;
                    using System.Threading.Tasks;

                    class Program
                    {
                        static async Task Main(string[] args)
                        {
                            var url = "https://example.com/api/v1/payment/create-payment";
                            var payload = new
                            {
                                amount = "1100",
                                reference = "iuy87dFfJ",
                                currency = "BDT",
                                callback_url = "https://example.com",
                                cust_name = "arif",
                                note = "test"
                            };
                            var headers = new
                            {
                                X_Authorization = "pk_test_123...",
                                X_Authorization_Secret = "sk_test_456...",
                                Content_Type = "application/json"
                            };

                            using (var client = new HttpClient())
                            {
                                client.DefaultRequestHeaders.Add("X-Authorization", headers.X_Authorization);
                                client.DefaultRequestHeaders.Add("X-Authorization-Secret", headers.X_Authorization_Secret);
                                client.DefaultRequestHeaders.Add("Content-Type", headers.Content_Type);

                                var content = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(payload), Encoding.UTF8, "application/json");
                                var response = await client.PostAsync(url, content);
                                var result = await response.Content.ReadAsStringAsync();
                                Console.WriteLine(result);
                            }
                        }
                    }

Property Definition

Property Type Example Mandatory Definition
amount numeric 100.00 yes Amount will be used as merchant payment
reference varchar(min:3, max: 20) inv-0215285852 yes Customer invoice/tracking number will be used as reference
currency varchar(4) BDT yes Always pass BDT as value
callback_url text https://example.com/callback.php yes A valid and working URL where the customer will be redirected after successful/failed payment
cust_name varchar(255) Ariful Islam yes Customer name should be passed here
note varchar(100) some text no Additional notes or comments

Response Examples

{
                        "success": true,
                        "message": "Payment request created successfully",
                        "data": {
                            "request_id": "c05a584911240b30f525041959c5c38540fdd5f34639b214b9",
                            "amount": "100",
                            "reference": "5w21rm54e4FD",
                            "currency": "BDT",
                            "issue_time": "2025-03-06 23:54:44",
                            "payment_url": "https://ipaybd.net/checkout/c05a584911240b30f525041959c5c38540fdd5f34639b214b9?expires=1741319684&signature=6294408b326cf940cad20816cda5aa96c234fcabfeef49d013be6e6daeb9514e"
                        }
                    }
Error Responses
{
                        "success": false,
                        "code": 403,
                        "message": "not authorized"
                    }
{
                        "success": false,
                        "message": "Data validation error",
                        "data": {
                            "reference": [
                                "Duplicate reference-id iuy8767jyLKgJDKgFfJ"
                            ]
                        }
                    }
{
                        "success": false,
                        "message": "Data validation error",
                        "data": {
                            "amount": [
                                "The amount field is required."
                            ],
                            "reference": [
                                "The reference field is required."
                            ]
                        }
                    }
{
                        "success": false,
                        "message": "Data validation error",
                        "data": {
                            "amount": [
                                "The amount field must be a number."
                            ]
                        }
                    }
===========Payment Callback Handler===========
 Handle callback URL parameters
 Sample Success URL:
 http://127.0.0.1:5500/?payment=success&payment_method=rocket&
request_id=7dc7ae27c564e9bffcc72d3d3f10fc69b50998fe24ff0cd566&reference
=ref_usx60cisvas8886&sim_id=01893087273&trxid=DR123456&amount=50

 Sample Cancel URL:
 http://127.0.0.1:5500/?payment=Cancelled

 Status codes:
 payment = success
 payment = rejected
 payment = Cancelled
 payment = pending

Track Payment Status

Use this endpoint to track the status of a payment using the referenceId. The response will include details about the payment, such as its status, amount, and customer information.

cURL Request Example

curl -X GET "https://example.com/api/v1/track-status/REF12345" \
                    -H "X-Authorization: pk_test_123..." \
                    -H "X-Authorization-Secret: sk_test_456..."

Response Examples

Below are examples of the responses you might receive when calling this endpoint:

Success Response

If the payment is found, the response will include the payment details and status information. 

{
                        "status": "true",
                        "data": {
                            "request_id": "12345",
                            "amount": "100.00",
                            "payment_method": "credit_card",
                            "reference": "REF12345",
                            "cust_name": "John Doe",
                            "cust_phone": "+1234567890",
                            "note": "Test payment",
                            "reject_msg": null,
                            "payment_method_trx": "trx_67890",
                            "status": pending, //pending,rejected,completed
                        }
                    }

Details about the possible statuses (e.g., pending, completed, Rejected).

Error Response

If the payment is not found or the referenceId is invalid, the response will indicate the error. 

{
                        "status": "false",
                        "message": "Data Not found"
                    }

Response Field Details

Here's a breakdown of the fields in the response:

Field Type Description
status string Indicates whether the request was successful (true) or not (false).
data object Contains the payment details if the request is successful.
request_id string The unique ID of the payment request.
amount numeric The amount of the payment.
payment_method string The payment method used (e.g., credit_card).
reference string The reference ID provided during payment creation.
cust_name string The name of the customer.
cust_phone string The phone number of the customer.
note string Additional notes provided during payment creation.
reject_msg string The rejection message, if the payment was rejected.
payment_method_trx string The transaction ID from the payment method.
Status string Details about the possible statuses (e.g., pending, Completed, Rejected).
Create Withdraw

Use this endpoint to create a cash-in request for a customer. The request will deduct the specified amount from the merchant's balance and initiate a payment to the customer's mobile financial service (MFS) account. The response will include a unique transaction ID (trxid) for tracking the payment status.

Endpoint

POST /api/v1/mfs/create

HTTP Request Examples

curl -X POST "http://localhost:8000/api/v1/mfs/create" \
                    -H "Content-Type: application/json" \
                    -d '{                       
                        "amount": 20,
                        "mfs_operator": "bkash",
                        "cust_number":"0123456789",
                        "withdraw_id":"012458756"

                    }'
$curl = curl_init();

                    curl_setopt_array($curl, array(
                        CURLOPT_URL => "http://localhost:8000/api/v1/mfs/create",
                        CURLOPT_RETURNTRANSFER => true,
                        CURLOPT_HTTPHEADER => array(
                            "Content-Type: application/json"
                        ),
                        CURLOPT_POSTFIELDS => '{
                            "amount": 100.00,
                            "mfs_operator": "bKash",
                            "cust_number": "+8801712345678",
                             "withdraw_id":"012458756"
                        }'
                    ));

                    $response = curl_exec($curl);
                    curl_close($curl);
                    echo $response;
import requests

                    url = "http://localhost:8000/api/v1/mfs/create"
                    headers = {
                        "Content-Type": "application/json"
                    }
                    payload = {
                        "amount": 100.00,
                        "mfs_operator": "bKash",
                        "cust_number": "+8801712345678",
                         "withdraw_id":"012458756"
                    }

                    response = requests.post(url, json=payload, headers=headers)
                    print(response.json())
const url = "http://localhost:8000/api/v1/mfs/create";
                    const headers = {
                        "Content-Type": "application/json"
                    };
                    const payload = {
                        amount: 100.00,
                        mfs_operator: "bKash",
                        cust_number: "+8801712345678",
                         withdraw_id:"012458756"
                    };

                    fetch(url, {
                        method: "POST",
                        headers: headers,
                        body: JSON.stringify(payload)
                    })
                    .then(response => response.json())
                    .then(data => console.log(data))
                    .catch(error => console.error(error));
using System;
                    using System.Net.Http;
                    using System.Text;
                    using System.Threading.Tasks;

                    class Program
                    {
                        static async Task Main(string[] args)
                        {
                            var url = "http://localhost:8000/api/v1/mfs/create";
                            var payload = new
                            {
                                amount = 100.00,
                                mfs_operator = "bKash",
                                cust_number = "+8801712345678",
                                 withdraw_id ="012458756"
                            };
                            var headers = new
                            {
                                Content_Type = "application/json"
                            };

                            using (var client = new HttpClient())
                            {
                                client.DefaultRequestHeaders.Add("Content-Type", headers.Content_Type);

                                var content = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(payload), Encoding.UTF8, "application/json");
                                var response = await client.PostAsync(url, content);
                                var result = await response.Content.ReadAsStringAsync();
                                Console.WriteLine(result);
                            }
                        }
                    }

Request Parameters

The following parameters are required to create a cash-in request:

Field Type Description
amount numeric The amount to be transferred to the customer's MFS account.
mfs_operator string The name of the MFS operator (e.g., bKash, Nagad).
cust_number string The customer's mobile number registered with the MFS operator.
withdraw_id withdraw_id The withdraw_id is unique.

Response Examples

Below are examples of the responses you might receive when calling this endpoint:

Success Response

If the cash-in request is successfully created, the response will include the transaction ID (trxid). 

{
                        "status": "success",
                        "trxid": "TRX-12345-20231010123456-5678"
                    }

Error Response

If the request fails due to validation errors or insufficient merchant balance, the response will indicate the error. 

{
                        "status": "false",
                        "message": "Amount is greater than Merchant Balance"
                    }

Response Field Details

Here's a breakdown of the fields in the response:

Field Type Description
status string Indicates whether the request was successful (success) or not (false).
trxid string The unique transaction ID for tracking the payment status.
message string A message describing the error, if the request fails.

Check Transaction Status

Use this endpoint to check the status of a transaction using the trnx_id. The response will include details about the transaction, such as its status, amount, and associated MFS information.

Endpoint

POST /api/v1/mfs/status_check

HTTP Request Examples

curl -X POST "https://example.com/api/v1/mfs/status_check" \
                    -H "X-Authorization: pk_test_123..." \
                    -H "X-Authorization-Secret: sk_test_456..." \
                    -H "Content-Type: application/json" \
                    -d '{
                        "trnx_id": "TRX-12345-20231010123456-5678"
                    }'
$curl = curl_init();

                    curl_setopt_array($curl, array(
                        CURLOPT_URL => "https://example.com/api/v1/mfs/status_check",
                        CURLOPT_RETURNTRANSFER => true,
                        CURLOPT_HTTPHEADER => array(
                            "X-Authorization: pk_test_123...",
                            "X-Authorization-Secret: sk_test_456...",
                            "Content-Type: application/json"
                        ),
                        CURLOPT_POSTFIELDS => '{
                            "trnx_id": "TRX-12345-20231010123456-5678"
                        }'
                    ));

                    $response = curl_exec($curl);
                    curl_close($curl);
                    echo $response;
import requests

                    url = "https://example.com/api/v1/mfs/status_check"
                    headers = {
                        "X-Authorization": "pk_test_123...",
                        "X-Authorization-Secret": "sk_test_456...",
                        "Content-Type": "application/json"
                    }
                    payload = {
                        "trnx_id": "TRX-12345-20231010123456-5678"
                    }

                    response = requests.post(url, json=payload, headers=headers)
                    print(response.json())
const url = "https://example.com/api/v1/mfs/status_check";
                    const headers = {
                        "X-Authorization": "pk_test_123...",
                        "X-Authorization-Secret": "sk_test_456...",
                        "Content-Type": "application/json"
                    };
                    const payload = {
                        trnx_id: "TRX-12345-20231010123456-5678"
                    };

                    fetch(url, {
                        method: "POST",
                        headers: headers,
                        body: JSON.stringify(payload)
                    })
                    .then(response => response.json())
                    .then(data => console.log(data))
                    .catch(error => console.error(error));
using System;
                    using System.Net.Http;
                    using System.Text;
                    using System.Threading.Tasks;

                    class Program
                    {
                        static async Task Main(string[] args)
                        {
                            var url = "https://example.com/api/v1/mfs/status_check";
                            var payload = new
                            {
                                trnx_id = "TRX-12345-20231010123456-5678"
                            };
                            var headers = new
                            {
                                X_Authorization = "pk_test_123...",
                                X_Authorization_Secret = "sk_test_456...",
                                Content_Type = "application/json"
                            };

                            using (var client = new HttpClient())
                            {
                                client.DefaultRequestHeaders.Add("X-Authorization", headers.X_Authorization);
                                client.DefaultRequestHeaders.Add("X-Authorization-Secret", headers.X_Authorization_Secret);
                                client.DefaultRequestHeaders.Add("Content-Type", headers.Content_Type);

                                var content = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(payload), Encoding.UTF8, "application/json");
                                var response = await client.PostAsync(url, content);
                                var result = await response.Content.ReadAsStringAsync();
                                Console.WriteLine(result);
                            }
                        }
                    }

Request Parameters

The following parameters are required to check the transaction status:

Field Type Description
trnx_id string The unique transaction ID to check the status for.

Response Examples

Below are examples of the responses you might receive when calling this endpoint:

Success Response

If the transaction is found, the response will include the transaction details and status. 

{
                        {
    "status": "true",
    "data": {
        "withdraw_number": "01448898189",
        "mfs_operator": "bkash",
        "amount": "20",
        "msg": "[ Carrier info, Amount too low to transact., OK]",
        "status": "pending"
    }

                    }

Details about the possible statuses (e.g., pending, success, ejected).

Error Response

If the transaction is not found or the trnx_id is invalid, the response will indicate the error. 

{
                        "status": "false",
                        "message": "This TRXID not available"
                    }

Response Field Details

Here's a breakdown of the fields in the response:

Field Type Description
status string Indicates whether the request was successful (success) or not (false).
data object Contains the transaction details if the request is successful.
number string The customer's mobile number associated with the transaction.
mfs string The MFS operator used for the transaction (e.g., bKash).
amount numeric The amount of the transaction.
msg string The transaction ID provided in the request.
status string The current status of the transaction (pending, success, or rejected).

H2H Payment Integration

With H2H, merchants can also create their own payment iframe page under their own branding, giving customers a seamless payment experience inside the merchant’s platform.

H2H Payment Introduction

Payment Flow

  • Check Available Methods – First, check which payment methods are currently available from the system’s Available Methods API.
  • User Chooses a Method – The user selects a preferred payment method (e.g., bKash, Nagad, Rocket, Upay) and a deposit number from the available list.
  • Send Payment Request – After selection, the user sends a payment request including the method, deposit number, amount, reference ID, and callback URL.
  • System Creates Payment Request – The system validates the request, creates a new payment record, and returns the status with both a callback URL and a webhook URL.

H2H (Host-to-Host) payment integration connects businesses directly with mobile financial services like bKash, Nagad, Rocket, and Upay. It enables secure server-to-server communication so merchants can automate deposits and withdrawals in real time.

iPaybd supports this by providing a unique deposit number for each merchant, which can be shown inside the merchant’s custom iframe or application.

Get Available Payment Methods (v2)

Use this endpoint to retrieve a list of available payment methods (MFS operators) along with their associated SIM numbers and icons. This endpoint is part of the v2 API and requires authentication via X-Authorization and X-Authorization-Secret headers.

cURL Request Example

curl -X GET "https://example.com/api/v2/payment/available-method" \
                        -H "X-Authorization: pk_test_123..." \
                        -H "X-Authorization-Secret: sk_test_456..."

Request Headers

The following headers are required to authenticate the request:

Header Description
X-Authorization Your API public key for authentication.
X-Authorization-Secret Your API secret key for authentication.

Response Examples

Below is an example of the response you might receive when calling this endpoint:

Success Response

The response includes a list of available payment methods, their associated SIM numbers, and icons. 

[
    {
        "deposit_method": "nagad",
        "deposit_number": "018xxx33742",
        "icon": "https://ibotbd.com/payments/nagad.png"
    },
    {
        "deposit_method": "upay",
        "deposit_number": "0132xxx6627",
        "icon": "https://ibotbd.com/payments/upay.png"
    },
    {
        "deposit_method": "bkash",
        "deposit_number": "0163xxx9900",
        "icon": "https://ibotbd.com/payments/bkash.png"
    },
    {
        "deposit_method": "rocket",
        "deposit_number": "01xxx8164207",
        "icon": "https://ibotbd.com/payments/rocket.png"
    }
]

Response Field Details

Here's a breakdown of the fields in the response:

Field Type Description
deposit_method string The name of the payment method (e.g., bkash, nagad).
deposit_number string The SIM number associated with the payment method.
icon string The URL of the icon representing the payment method.

Create Payment (v2)

Use this endpoint to create a payment request. This endpoint is part of the v2 API and requires authentication via X-Authorization and X-Authorization-Secret headers. The payment request will be processed based on the provided details, such as amount, customer information, and payment method.

cURL Request Example

curl -X POST "https://example.com/api/v2/payment/create-payment" \
                        -H "X-Authorization: pk_test_123..." \
                        -H "X-Authorization-Secret: sk_test_456..." \
                        -H "Content-Type: application/json" \
                        -d '{
                                "amount": 50,
                                "reference": "Rvx99sS99",
                                "currency": "BDT",
                                "callback_url": "https://example.com/callback",
                                "transaction_id": "01JYG4GET7",
                                "from_number": "01712345678",
                                "payment_method":"rocket",
                                "deposit_number":"013358164207"
                                }'

Request Headers

The following headers are required to authenticate the request:

Header Description
X-Authorization Your API public key for authentication.
X-Authorization-Secret Your API secret key for authentication.

Request Parameters

The following parameters are required to create a payment request:

Field Type Description
amount numeric The amount of the payment.
reference string A unique reference ID for the payment (3-20 characters).
currency string The currency of the payment (e.g., BDT).
callback_url string The URL to receive payment status updates.
transaction_id string A unique transaction ID (8-10 alphanumeric characters).
from_number string The sender's phone number.
payment_method string The payment method (e.g., bkash, nagad).
deposit_number string The SIM number associated with the payment method.

Response Examples

Below are examples of the responses you might receive when calling this endpoint: 

{

    "status": "pending",
    "message": "Deposit is processing, check status using track or webhook_url | জমা প্রক্রিয়াধীন, অনুগ্রহপূর্বক অপেক্ষা করুন",
    "callback": "https://example.com/callback?status=pending&reference=Rvx99ssS99&transaction_id=01JYG4GET7&payment_method=rocket"
}

Details about the possible statuses (e.g., pending, completed, Rejected).

Response Field Details

Here's a breakdown of the fields in the response:

Field Type Description
status string The status of the payment request (success, pending, or error).
message string A message describing the result of the request.
Callback Url object A list of possible statuses for the payment request.

Track Payment Status (v2)

Use this endpoint to track the status of a payment using the referenceId. This endpoint is part of the v2 API and requires authentication via X-Authorization and X-Authorization-Secret headers. The response will include details about the payment, such as its status, amount, and customer information.

cURL Request Example

curl -X GET "https://example.com/api/v2/payment/status-track/REF12345" \
                        -H "X-Authorization: pk_test_123..." \
                        -H "X-Authorization-Secret: sk_test_456..."

Request Headers

The following headers are required to authenticate the request:

Header Description
X-Authorization Your API public key for authentication.
X-Authorization-Secret Your API secret key for authentication.

Request Parameters

The following parameter is required to track the payment status:

Field Type Description
referenceId string The unique reference ID of the payment to track.

Response Examples

Below are examples of the responses you might receive when calling this endpoint:

Success Response

If the payment is found, the response will include the payment details and status information. 

{
    "status": "true",
    "data": {
        "request_id": "4305381816f2515178de5b02b3b819551ca437a75f98b966d3",
        "amount": 50,
        "payment_method": "rocket",
        "reference": "Rvx99sS99",
        "cust_name": null,
        "cust_phone": null,
        "note": null,
        "reject_msg": null,
        "payment_method_trx": "01JYG4GET7",
        "status": "pending"
    }
}

Status can be pending, success , rejected

Error Response

If the payment is not found or the referenceId is invalid, the response will indicate the error. 

{
                        "status": "false",
                        "message": "Data Not found"
                    }

Response Field Details

Here's a breakdown of the fields in the response:

Field Type Description
status string Indicates whether the request was successful (true) or not (false).
data object Contains the payment details if the request is successful.
request_id string The unique ID of the payment request.
amount numeric The amount of the payment.
payment_method string The payment method used (e.g., bkash, nagad).
reference string The reference ID provided during payment creation.
cust_name string The name of the customer.
note string Additional notes provided during payment creation.
reject_msg string The rejection message, if the payment was rejected.
payment_method_trx string The transaction ID from the payment method.
status numeric The current status of the payment.