Trustpaybd - Modern Payment Gateway and Withdraw Solutions for Bangladeshi Mobile Banking

Documentation

Overview
Getting Started

Overview

What is Trustpaybd?

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

Instant Collection via bKash, Nagad, Rocket, Upay

Automated Withdrawals to customer wallets

Real-Time Validation of transaction data

JSON API with HTTP request/response

Webhook Support for instant 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

Account Setup

Create an account and get your API keys

Integration

Implement payment flow using our APIs

Testing

Test integration using test API keys

Go Live

Switch to production keys and start accepting payments

Getting Started

Follow these steps to start accepting payments with Trustpaybd.

Base URL

www.dev.trustpaybd.net

1. Get Your API Keys

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

Smart Checkout

Optional

Smart Checkout allows you to skip the payment method selection page by specifying deposit_method and type in your Create Payment request. The customer will be redirected directly to the transaction input page for the specified payment method.

POST /api/v1/payment/create-payment

How It Works

Without Smart Checkout

Customer is redirected to the payment method selection page where they choose their preferred MFS operator and type.

With Smart Checkout

Customer skips method selection and lands directly on the transaction input page for the specified deposit method and type.

Smart Checkout Parameters

Add these optional fields to your existing Create Payment request body:

Property	Type	Values	Mandatory	Definition
deposit_method	string	`bkash` `nagad` `rocket` `upay`	no (required with type)	MFS operator name. Must be sent together with `type`.
type	string	`P2A` `P2C` `P2P`	no (required with deposit_method)	Transaction type — P2A (Cash Out), P2C (Payment), P2P (Send Money). Must be sent together with `deposit_method`.

Example Request

curl -X POST "https://dev.trustpaybd.net/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": "inv_smart_001",
                        "currency": "BDT",
                        "callback_url": "https://example.com/callback",
                        "webhook_url": "https://example.com/webhook",
                        "cust_name": "Rahim",
                        "deposit_method": "bkash",
                        "type": "P2C",
                    }'

$curl = curl_init();

                    curl_setopt_array($curl, array(
                        CURLOPT_URL => "https://dev.trustpaybd.net/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": "inv_smart_001",
                            "currency": "BDT",
                            "callback_url": "https://example.com/callback",
                            "webhook_url": "https://example.com/webhook",
                            "cust_name": "Rahim",
                            "deposit_method": "bkash",
                            "type": "P2C",
                        }'
                    ));

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

import requests

                    url = "https://dev.trustpaybd.net/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": "inv_smart_001",
                        "currency": "BDT",
                        "callback_url": "https://example.com/callback",
                        "webhook_url": "https://example.com/webhook",
                        "cust_name": "Rahim",
                        "deposit_method": "bkash",
                        "type": "P2C",
                    }

                    response = requests.post(url, json=payload, headers=headers)
                    print(response.json())

const url = "https://dev.trustpaybd.net/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: "inv_smart_001",
                        currency: "BDT",
                        callback_url: "https://example.com/callback",
                        webhook_url: "https://example.com/webhook",
                        cust_name: "Rahim",
                        deposit_method: "bkash",
                        type: "P2C",
                    };

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

Important Notes

Both deposit_method and type must be provided together. Sending only one will be ignored.
If the specified method is not available at the time of checkout, the customer will see the standard payment method selection page instead.
The response format is identical to the standard Create Payment response — only the checkout behavior changes.

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://dev.trustpaybd.net/api/v1/payment/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`).

Checkout

POST /api/v1/payment/create-payment

HTTP Request Examples

curl -X POST "https://dev.trustpaybd.net/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",
                        "webhook_url": "https://example.com",
                        "cust_name": "arif",
                        "note": "test"
                    }'

$curl = curl_init();

                    curl_setopt_array($curl, array(
                        CURLOPT_URL => "https://dev.trustpaybd.net/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",
                            "webhook_url": "https://example.com",
                            "cust_name": "arif",
                            "note": "test"
                        }'
                    ));

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

import requests

                    url = "https://dev.trustpaybd.net/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",
                        "webhook_url": "https://example.com",
                        "cust_name": "arif",
                        "note": "test"
                    }

                    response = requests.post(url, json=payload, headers=headers)
                    print(response.json())

const url = "https://dev.trustpaybd.net/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://dev.trustpaybd.net/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://dev.trustpaybd.net/api/v1/payment/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`).

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://dev.trustpaybd.net/api/v1/payment/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`).

v2 Host-to-Host

H2H Payment API

A white-label payment gateway that lets you build your own branded checkout — no redirects, full control.

White-Label Payment Gateway

H2H (Host-to-Host) Payment API is a white-label payment gateway system that allows you to build your own custom payment checkout page under your own branding. Instead of redirecting customers to a third-party checkout, you have full control over the payment UI and user experience within your own platform.

Introduction

With the H2H Payment API, merchants integrate directly via server-to-server communication with mobile financial services such as bKash, Nagad, Rocket, and Upay. You design and host your own checkout page — iPaybd handles the payment processing behind the scenes.

Payment Flow

Check Available Methods

Query the Available Methods API to see which payment methods are currently active in the system.

User Chooses a Method

The user selects a preferred payment method (e.g., bKash, Nagad, Rocket, Upay) and a deposit number from the list.

Send Payment Request

Submit a payment request including the method, deposit number, amount, reference ID, and callback URL.

System Creates Payment

The system validates the request, creates a payment record, and returns the status with callback & webhook URLs.

iPaybd provides a unique deposit number for each merchant, which can be displayed inside the merchant's custom checkout page or application — giving customers a seamless, fully branded payment experience.

Get Available Payment Methods

GET

Retrieve a list of available payment methods (MFS operators) along with their associated SIM numbers and icons. Requires authentication via X-Authorization and X-Authorization-Secret headers.

GET https://dev.trustpaybd.net/api/v2/payment/available-method

cURL Example

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

Request Headers

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

Success Response

Returns a list of available payment methods with their SIM numbers and icons.

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

Response Fields

Field	Type	Description
`deposit_method`	string	Name of the payment method (e.g., `bkash`, `nagad`).
`deposit_number`	string	The SIM number associated with the payment method.
`icon`	string	URL of the icon representing the payment method.
`type`	string	Payment type — `P2C` (Partner to Customer) or `P2A` (Partner to Agent).

Create Payment

POST

Create a payment request using the v2 API. Requires authentication via X-Authorization and X-Authorization-Secret headers. The payment will be processed based on the provided amount, method, and customer details.

POST https://dev.trustpaybd.net/api/v2/payment/create-payment

cURL Examples

curl -X POST "https://dev.trustpaybd.net/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",
    "webhook_url": "https://example.com/webhook",
    "transaction_id": "01JYG4GET7",
    "from_number": "01712345678",
    "payment_method": "rocket",
    "deposit_number": "013358164207",
    "type": "P2A"
  }'

curl -X POST "https://dev.trustpaybd.net/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",
    "webhook_url": "https://example.com/webhook",
    "payment_method": "bkash",
    "deposit_number": "013358164207",
    "type": "P2C"
  }'

Request Headers

Header	Required	Description
`X-Authorization`	Required	Your API public key for authentication.
`X-Authorization-Secret`	Required	Your API secret key for authentication.
`Content-Type`	Required	`application/json`

Request Parameters

Field	Type	Required	Description
`amount`	numeric	Required	The amount of the payment.
`reference`	string	Required	A unique reference ID for the payment (3–20 characters).
`currency`	string	Required	Currency code (e.g., `BDT`).
`callback_url`	string	Required	URL to receive payment status updates.
`transaction_id`	string	P2A Only	A unique transaction ID (8–10 alphanumeric characters).
`from_number`	string	P2A Only	The sender's phone number.
`payment_method`	string	Required	Payment method (e.g., `bkash`, `nagad`, `rocket`, `upay`).
`deposit_number`	string	Required	The SIM number associated with the payment method.
`type`	string	Required	`P2A` (Partner to Agent) or `P2C` (Partner to Customer).
`webhook_url`	string	Optional	A valid URL to receive webhook notifications (POST) when the payment status changes (completed or rejected). See Webhook section.

Response Examples

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

Possible statuses: pending completed rejected

{
    "status": true,
    "message": "Data submitted successfully",
    "data": {
        "sim_id": "01871168733",
        "amount": 10,
        "payment_method": "api_bkash",
        "reference": "turag05",
        "currency": "BDT",
        "callback_url": "https://google.com/",
        "cust_name": null,
        "issue_time": "2025-09-17 21:22:20"
    },
    "type": "P2C",
    "URL": "https://payment.bkash.com/?paymentId=..."
}

For P2C, the response includes a URL field. Redirect the customer to this URL to complete the payment.

Response Fields

Field	Type	Description
`status`	string \| boolean	Payment request status (`pending`, `success`, or `error`).
`message`	string	Human-readable message describing the result.
`callback`	string	Callback URL with appended query parameters (P2A only).
`URL`	string	Payment URL to redirect the customer (P2C only).

Payment Callback Handler

When a payment is processed, the system redirects the user to your callback_url with query parameters:

Success Callback Example

https://yoursite.com/callback?payment=success&payment_method=rocket&request_id=7dc7ae27c564...&reference=ref_usx60cisvas8886&sim_id=01893087273&trxid=DR123456&amount=50

Cancel Callback Example

https://yoursite.com/callback?payment=Cancelled

Possible Status Codes

payment = success payment = rejected payment = Cancelled payment = pending

Track Payment Status

GET

Track the status of a payment using the referenceId. Requires authentication via X-Authorization and X-Authorization-Secret headers.

GET https://dev.trustpaybd.net/api/v2/payment/status-track/{referenceId}

cURL Example

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

Request Headers

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

Request Parameters

Field	Type	Required	Description
`referenceId`	string	Required	The unique reference ID of the payment to track (URL path parameter).

Response Examples

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

The status field inside data can be: pending success rejected

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

Response Fields

Field	Type	Description
`status`	string	`true` if found, `false` if not.
`data`	object	Payment details object (only present on success).
`data.request_id`	string	Unique ID of the payment request.
`data.amount`	numeric	Payment amount.
`data.payment_method`	string	Payment method used.
`data.reference`	string	Reference ID from payment creation.
`data.cust_name`	string \| null	Customer name.
`data.reject_msg`	string \| null	Rejection reason (if payment was rejected).
`data.payment_method_trx`	string	Transaction ID from the payment method.
`data.status`	string	Current payment status (`pending`, `success`, `rejected`).

Webhook

POST

Webhooks allow you to receive real-time notifications when a payment status changes. When a payment is completed or rejected, the system will send a POST request to both your callback_url and webhook_url (if provided during payment creation).

How It Works

Create Payment

Include webhook_url in your create-payment request.

Status Changes

Payment is processed and status changes to completed or rejected.

Receive Notification

System sends a POST request with payment data to your webhook URL.

Webhook Payload

The following JSON payload will be sent as a POST request to your callback_url and webhook_url:

{
    "status": "true",
    "data": {
        "request_id": "c05a584911240b30f525041959c5c38540fdd5f34639b214b9",
        "amount": 50,
        "payment_method": "rocket",
        "reference": "Rvx99sS99",
        "cust_name": "Rahim",
        "cust_phone": "+8801712345678",
        "note": null,
        "reject_msg": null,
        "payment_method_trx": "01JYG4GET7",
        "status": "1",
        "status_name": "completed"
    }
}

Payload Fields

Field	Type	Description
`status`	string	Always `"true"` when webhook is sent.
`data.request_id`	string	Unique payment request ID generated by the system.
`data.amount`	numeric	Payment amount.
`data.payment_method`	string	Payment method used (e.g., `bkash`, `nagad`, `rocket`, `upay`).
`data.reference`	string	Your unique reference ID provided during payment creation.
`data.cust_name`	string \| null	Customer name.
`data.cust_phone`	string \| null	Customer phone number.
`data.note`	string \| null	Additional note provided during payment creation.
`data.reject_msg`	string \| null	Rejection reason (only present when payment is rejected).
`data.payment_method_trx`	string	Transaction ID from the MFS operator.
`data.status`	string	Numeric status code: `1` or `2` = completed, `3` = rejected.
`data.status_name`	string	Human-readable status: `completed` or `rejected`.

Webhook Handler Example (PHP)

<?php
// webhook.php — Your webhook endpoint

$payload = json_decode(file_get_contents('php://input'), true);

if ($payload && isset($payload['data'])) {
    $data = $payload['data'];
    $reference = $data['reference'];
    $statusName = $data['status_name']; // 'completed' or 'rejected'
    $amount = $data['amount'];
    $trxId = $data['payment_method_trx'];

    if ($statusName === 'completed') {
        // Payment successful — update your order status
        // updateOrder($reference, 'paid', $amount, $trxId);
    } elseif ($statusName === 'rejected') {
        // Payment rejected
        $reason = $data['reject_msg'];
        // updateOrder($reference, 'failed', $amount, $reason);
    }

    // Respond with 200 to acknowledge receipt
    http_response_code(200);
    echo json_encode(['received' => true]);
} else {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid payload']);
}

Important Notes

Webhooks are only sent for completed (status 1, 2) and rejected (status 3) payments. Pending payments do not trigger webhooks.
The webhook is sent as a POST request with Content-Type: application/json.
The system sends the webhook to both callback_url and webhook_url if both are provided. You can use either or both.
Your webhook endpoint must respond within 10 seconds. Requests that time out will be logged as failed.
Always verify the reference and amount in the webhook data against your records before updating order status.
Return HTTP 200 from your webhook endpoint to acknowledge receipt.

v1 Withdraw

Withdraw API

Withdraw funds directly to customer mobile wallets via bKash, Nagad, Rocket, and more — instantly and automatically.

Automated Withdrawal System

The Withdraw API enables merchants to send funds directly to customers' mobile financial service (MFS) accounts. The specified amount is deducted from the merchant's balance and transferred to the customer's wallet automatically.

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",
                        "webhook_url": "https://example.com/withdraw-callback"
                    }'

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

                            using (var client = new HttpClient())
                            {
                                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 withdraw 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`	string	The withdraw_id is unique.

Response Examples

Success Response

If the withdraw 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.

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

Response Field Details

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://dev.trustpaybd.net/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://dev.trustpaybd.net/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://dev.trustpaybd.net/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://dev.trustpaybd.net/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://dev.trustpaybd.net/api/v1/mfs/status_check";
                            var payload = new
                            {
                                trnx_id = "TRX-12345-20231010123456-5678"
                            };

                            using (var client = new HttpClient())
                            {
                                client.DefaultRequestHeaders.Add("X-Authorization", "pk_test_123...");
                                client.DefaultRequestHeaders.Add("X-Authorization-Secret", "sk_test_456...");

                                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

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

Response Examples

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: pending, success, rejected.

Error Response

If the transaction is not found or the trnx_id is invalid.

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

Response Field Details

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

Developer Documentation

Documentation

Overview

What is Trustpaybd?

Architecture Overview

Client Side

Server Side

Webhooks

Integration Process

Account Setup

Integration

Testing

Go Live

Getting Started

Base URL

1. Get Your API Keys

Smart Checkout

How It Works

Without Smart Checkout

With Smart Checkout

Smart Checkout Parameters

Example Request

Important Notes

Response Examples

Error Responses

Track Payment Status

cURL Request Example

Response Examples

Success Response

Error Response

Response Field Details

Checkout

HTTP Request Examples

Property Definition

Response Examples

Error Responses

Track Payment Status

cURL Request Example

Response Examples

Success Response

Error Response

Response Field Details

Track Payment Status

cURL Request Example

Response Examples

Success Response

Error Response

Response Field Details

H2H Payment API

White-Label Payment Gateway

Introduction

Payment Flow

Check Available Methods

User Chooses a Method

Send Payment Request

System Creates Payment

Get Available Payment Methods

cURL Example

Request Headers

Success Response

Response Fields

Create Payment

cURL Examples

Request Headers

Request Parameters

Response Examples

Response Fields

Track Payment Status

cURL Example

Request Headers

Request Parameters

Response Examples

Response Fields

Webhook

How It Works

Create Payment

Status Changes

Receive Notification

Webhook Payload

Payload Fields