Developer Documentation

Everything you need to integrate BDpay payments into your application.

Get Started API Reference

Documentation

Overview

i

What is BDpay?

BDpay 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

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 keys and start accepting payments

Getting Started

Follow these steps to start accepting payments with BDpay.

Base URL

bdpay.llc

1. Get Your API Keys

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

Checkout

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

Request Parameters

Property Type Example Mandatory Definition
amount numeric 1100 yes The payment amount.
reference string (3–20) inv_smart_001 yes Your unique invoice/tracking ID. Must be unique per merchant.
currency string BDT yes Always pass BDT.
callback_url url https://example.com/callback yes A valid URL where the customer is redirected after a successful/failed payment.
webhook_url url https://example.com/webhook no Server-to-server URL that receives the final payment status. See the Webhook section.
cust_name string Jhon yes Customer name.
cust_phone string +8801711XXYYZZ no Customer phone number.
deposit_method string bkash nagad rocket upay yes MFS operator name. Must be sent together with type.
type string P2A yes Transaction type — P2A (Cash Out). Must be sent together with deposit_method.

Example Request

curl -X POST "https://bdpay.llc/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": "Jhon",
                        "deposit_method": "bkash",
                        "type": "P2A",
                    }'
$curl = curl_init();

                    curl_setopt_array($curl, array(
                        CURLOPT_URL => "https://bdpay.llc/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": "Jhon",
                            "deposit_method": "bkash",
                            "type": "P2A",
                        }'
                    ));

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

                    url = "https://bdpay.llc/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": "Jhon",
                        "deposit_method": "bkash",
                        "type": "P2A",
                    }

                    response = requests.post(url, json=payload, headers=headers)
                    print(response.json())
const url = "https://bdpay.llc/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: "Jhon",
                        deposit_method: "bkash",
                        type: "P2A",
                    };

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

Webhook

POST

The Payment Webhook lets you receive the final status of a payment automatically, so you don't have to poll the Track Payment Status endpoint. When a payment is completed or rejected, the system sends a POST request in JSON format to the webhook_url (and/or callback_url) you provided when creating the payment.

How It Works

1

Create Payment

Include webhook_url in your Checkout / Create Payment request.

2

Status Changes

Payment is processed and status changes to completed or rejected.

3

Receive Notification

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

Sample Webhook Payload

The following JSON payload is sent as a POST request to your webhook_url:

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

Key Fields

  • signature — SHA-256 HMAC signature of the data object, generated using your secret key.
  • data.reference — your unique reference ID; use this to match the webhook with your order.
  • data.status_name — completed or rejected.
  • data.status — numeric code: 1/2 = completed, 3 = rejected.
  • data.payment_method_trx — MFS-side transaction ID (for completed payments).
  • data.reject_msg — rejection reason (for rejected payments).

Important Notes

  • Webhooks are only sent for completed and rejected payments. Pending payments do not trigger webhooks.
  • Your endpoint must respond with HTTP 200 within 10 seconds to acknowledge receipt.
  • Always verify the reference and amount in the webhook against your records before updating order status.
  • If the webhook is missed or fails, you can always fetch the current status via the Track Payment Status endpoint below.

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://bdpay.llc/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:

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

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
statusstringIndicates whether the request was successful (true) or not (false).
dataobjectContains the payment details if the request is successful.
request_idstringThe unique ID of the payment request.
amountnumericThe amount of the payment.
payment_methodstringThe payment method used (e.g., credit_card).
referencestringThe reference ID provided during payment creation.
cust_namestringThe name of the customer.
cust_phonestringThe phone number of the customer.
notestringAdditional notes provided during payment creation.
reject_msgstringThe rejection message, if the payment was rejected.
payment_method_trxstringThe transaction ID from the payment method.
StatusstringDetails about the possible statuses (e.g., pending, Completed, Rejected).