API Documentation — ChaoPaoPay

Overview

Integrate PayIn and PayOut into your application using our simple REST API.

Base URL

https://demopay.rjcbd.sbs/api/v1/

PHP Integration Kit

Ready-to-use PHP files — config, payin, payout, webhook

Download Kit (.zip)

Request Format

All requests must be POST with Content-Type: application/json body. Responses are always JSON.

Authentication

All API requests require the following HTTP headers.

Header	Value	Required
`X-API-Key`	Your API Key (from merchant panel)	Yes
`X-Merchant-ID`	Your Merchant ID e.g. `M2024XXXXXX`	Yes
`Content-Type`	`application/json`	Yes

Secret Key is not needed for API calls — only for verifying incoming callbacks.

Example Headers

X-API-Key: your_api_key_here
X-Merchant-ID: M2024XXXXXX
Content-Type: application/json

Payment Channels

Channel	Code	PayIn	PayOut
bKash	`101`	✓ Supported	✓ Supported
Nagad	`102`	✓ Supported	✓ Supported

Currency is always BDT. More channels may be added in the future.

PayIn — Create Payment

Create a payment request and redirect your customer to the payment page.

POST /api/v1/payin/create.php

Request Parameters

Parameter	Type	Description	Required
`trx_id`	string	Your unique transaction ID	Yes
`amount`	decimal	Payment amount e.g. `100.50`	Yes
`method_code`	integer	`101`=bKash, `102`=Nagad	Yes
`customer_name`	string	Customer full name	Yes
`callback_url`	string	Webhook URL for status notifications	Yes
`customer_email`	string	Customer email	Optional
`customer_phone`	string	Customer phone number	Optional
`customer_address`	string	Customer address	Optional
`description`	string	Payment description / note	Optional
`return_url`	string	Redirect URL after payment completes	Optional

Example Request

$data = [
    'trx_id'         => 'PAY-' . time(),
    'amount'         => 1500.00,
    'method_code'    => 101,
    'customer_name'  => 'John Doe',
    'callback_url'   => 'https://yourdomain.com/webhook/payin',
    'customer_email' => 'john@example.com',
    'customer_phone' => '+8801234567890',
    'return_url'     => 'https://yourdomain.com/success',
];

$ch = curl_init('https://demopay.rjcbd.sbs/api/v1/payin/create.php');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: YOUR_API_KEY',
    'X-Merchant-ID: YOUR_MERCHANT_ID',
]);
$result = json_decode(curl_exec($ch), true);

if ($result['success']) {
    header('Location: ' . $result['data']['payment_url']);
}

Success Response

{
    "success": true,
    "message": "Payment request created",
    "data": {
        "transaction_id": "TRX20241201ABC123",
        "trx_id": "PAY-123456",
        "amount": 1500.00,
        "currency": "BDT",
        "status": "pending",
        "payment_url": "https://demopay.rjcbd.sbs/pay/TRX20241201ABC123"
    }
}

PayOut — Withdrawal

Submit a payout request to send funds to a bKash or Nagad account.

POST /api/v1/payout/create.php

Request Parameters

Parameter	Type	Description	Required
`trx_id`	string	Your unique transaction ID	Yes
`amount`	decimal	Withdrawal amount	Yes
`method_code`	integer	`101`=bKash, `102`=Nagad	Yes
`account_number`	string	Recipient wallet number	Yes
`account_name`	string	Recipient full name	Yes
`notify_url`	string	Webhook URL for status updates	Yes
`description`	string	Payout note / reference	Optional

Example Request

$data = [
    'trx_id'            => 'WIT-' . time(),
    'amount'            => 1000.00,
    'method_code'       => 101,
    'account_number'    => '01712345678',
    'account_name'      => 'John Doe',
    'notify_url'        => 'https://yourdomain.com/webhook/payout',
    'description'       => 'Commission payout',
];

$ch = curl_init('https://demopay.rjcbd.sbs/api/v1/payout/create.php');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: YOUR_API_KEY',
    'X-Merchant-ID: YOUR_MERCHANT_ID',
]);
$result = json_decode(curl_exec($ch), true);

Success Response

{
    "success": true,
    "message": "Payout request submitted",
    "data": {
        "transaction_id": "TRX20241201PAY456",
        "trx_id": "WIT-001",
        "amount": 1000.00,
        "fee": 20.00,
        "net_amount": 1000.00,
        "currency": "BDT",
        "status": "pending",
        "account_number": "017***5678"
    }
}

Check Status

Query the current status of any transaction.

POST /api/v1/transaction/status.php

Request

// By system transaction_id
{ "transaction_id": "TRX20241201ABC123" }

// OR by your own trx_id
{ "trx_id": "PAY-123456" }

Transaction Status Values

pending — Awaiting payment or processing
processing — Payment in progress
completed — Successfully completed
failed — Payment failed
cancelled — Payout cancelled
refunded — Amount refunded

Callback / Webhook

We send a POST request to your callback_url whenever a transaction status changes.

Always verify the signature to ensure the callback is genuinely from us. Return HTTP 200 to acknowledge.

Callback Payload

{
    "transaction_id": "TRX20241201ABC123",
    "trx_id": "PAY-123456",
    "type": "payin",
    "amount": 1500.00,
    "currency": "BDT",
    "status": "completed",
    "customer_name": "John Doe",
    "updated_at": "2024-12-01T14:35:00+06:00",
    "signature": "sha256_hash"
}

Secret Key is different from your API Key. Find it in your Merchant Panel under API Settings.

Verify Signature (PHP)

$secretKey = 'YOUR_SECRET_KEY_FROM_MERCHANT_PANEL';
$data = json_decode(file_get_contents('php://input'), true);

$expected = hash('sha256',
    $data['transaction_id'] .
    $data['trx_id'] .
    $data['status'] .
    $secretKey
);

if ($data['signature'] === $expected) {
    // Valid — update your order
    echo json_encode(['success' => true]);
} else {
    http_response_code(400);
    echo json_encode(['success' => false]);
}

Error Codes

Code	HTTP	Description
AUTH_FAILED	401	Invalid API Key or Merchant ID
INSUFFICIENT_BALANCE	402	Not enough balance for payout
INVALID_PARAMS	400	Missing or invalid request parameters
DUPLICATE_ORDER	409	Transaction ID already exists
INVALID_WITHDRAW_PASS	403	Incorrect withdrawal password
ACCOUNT_SUSPENDED	403	Merchant account suspended
SERVER_ERROR	500	Internal server error

API Reference