Developer Documentation

Everything you need to integrate iPayBD payments into your application.

Get Started API Reference

Documentation

Overview

iPayBD provides a robust payment processing platform with features designed to help you accept payments globally. Our API allows you to:

  • Accept payments in 135+ currencies
  • Process credit cards, digital wallets, and local payment methods
  • Handle subscriptions and recurring payments
  • Manage refunds and disputes

Architecture Overview

Client Side

Secure collection of payment details using our JS SDK

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 SDKs

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

ipaybd.net

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",
                        "cust_phone": "+855454454",
                        "cust_address": "dhaka",
                        "checkout_items": {
                            "item1": {
                                "name": "Product1",
                                "size": "50kg",
                                "shape": "square"
                            },
                            "item2": {
                                "name": "Product2",
                                "size": "100kg",
                                "shape": "round"
                            }
                        },
                        "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",
                            "cust_phone": "+855454454",
                            "cust_address": "dhaka",
                            "checkout_items": {
                                "item1": {
                                    "name": "Product1",
                                    "size": "50kg",
                                    "shape": "square"
                                },
                                "item2": {
                                    "name": "Product2",
                                    "size": "100kg",
                                    "shape": "round"
                                }
                            },
                            "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",
                        "cust_phone": "+855454454",
                        "cust_address": "dhaka",
                        "checkout_items": {
                            "item1": {
                                "name": "Product1",
                                "size": "50kg",
                                "shape": "square"
                            },
                            "item2": {
                                "name": "Product2",
                                "size": "100kg",
                                "shape": "round"
                            }
                        },
                        "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",
                        cust_phone: "+855454454",
                        cust_address: "dhaka",
                        checkout_items: {
                            item1: {
                                name: "Product1",
                                size: "50kg",
                                shape: "square"
                            },
                            item2: {
                                name: "Product2",
                                size: "100kg",
                                shape: "round"
                            }
                        },
                        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",
                                cust_phone = "+855454454",
                                cust_address = "dhaka",
                                checkout_items = new
                                {
                                    item1 = new
                                    {
                                        name = "Product1",
                                        size = "50kg",
                                        shape = "square"
                                    },
                                    item2 = new
                                    {
                                        name = "Product2",
                                        size = "100kg",
                                        shape = "round"
                                    }
                                },
                                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
cust_phone varchar(15) +8801711XXYYZZ yes Customer phone number should be passed here
cust_address varchar(100) Dhaka, Bangladesh no Customer address should be passed here
checkout_items array [ ] no Merchant may pass multiple product items or other types of data as an array
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."
                            ]
                        }
                    }

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": 1,
                            "statusDetails": {
                                "pending": 0,
                                "Completed": [1, 2],
                                "Rejected": 3
                            }
                        }
                    }

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 numeric The current status of the payment.
statusDetails object 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": 100.00,
                        "mfs_operator": "bKash",
                        "cust_number": "+8801712345678"
                    }'
$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"
                        }'
                    ));

                    $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"
                    }

                    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"
                    };

                    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"
                            };
                            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.

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/status_check

HTTP Request Examples

curl -X POST "https://example.com/api/v1/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/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/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/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/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": "success",
                        "data": {
                            "number": "+8801712345678",
                            "mfs": "bKash",
                            "amount": 100.00,
                            "msg": "TRX-12345-20231010123456-5678",
                            "status": "success"
                        }
                    }

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).

Payment Integration

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. 

[
                        {
                            "payment_method": "bkash",
                            "sim_number": "1234567890",
                            "icon": "https://example.com/payments/bkash.png"
                        },
                        {
                            "payment_method": "nagad",
                            "sim_number": "0987654321",
                            "icon": "https://example.com/payments/nagad.png"
                        }
                    ]

Response Field Details

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

Field Type Description
payment_method string The name of the payment method (e.g., bkash, nagad).
sim_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": 100.00,
                            "reference": "REF12345",
                            "currency": "BDT",
                            "callback_url": "https://example.com/callback",
                            "cust_name": "John Doe",
                            "cust_phone": "+8801712345678",
                            "cust_address": "123 Main St",
                            "transaction_id": "TRX123456",
                            "from_number": "+8801712345678",
                            "payment_method": "bkash",
                            "sim_number": "1234567890"
                        }'

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.
cust_name string The name of the customer (3-50 characters).
cust_phone string The phone number of the customer (3-15 characters).
cust_address string The address of the customer (optional, 3-100 characters).
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).
sim_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:

Success Response

If the payment request is successfully created and processed, the response will include the status and a success message. 

{
                        "status": "success",
                        "message": "Transaction is successful",
                        "possible_status": {
                            "pending": 0,
                            "success": 1,
                            "failed": 2
                        }
                    }

Pending Response

If the payment request is created but still processing, the response will indicate a pending status. 

{
                        "status": "pending",
                        "message": "Transaction is processing",
                        "possible_status": {
                            "pending": 0,
                            "success": 1,
                            "failed": 2
                        }
                    }

Error Response

If the payment request fails due to validation errors or other issues, the response will indicate the error. 

{
                        "status": "error",
                        "message": "Please contact with admin",
                        "possible_status": {
                            "pending": 0,
                            "success": 1,
                            "failed": 2
                        }
                    }

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.
possible_status 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": "12345",
                            "amount": "100.00",
                            "payment_method": "bkash",
                            "reference": "REF12345",
                            "cust_name": "John Doe",
                            "cust_phone": "+8801712345678",
                            "note": "Test payment",
                            "reject_msg": null,
                            "payment_method_trx": "trx_67890",
                            "status": 1,
                            "statusDetails": {
                                "pending": 0,
                                "Completed": [1, 2],
                                "Rejected": 3
                            }
                        }
                    }

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.
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 numeric The current status of the payment.
statusDetails object Details about the possible statuses (e.g., pending, Completed, Rejected).