Secure withdrawal integration

Withdrawal lifecycle

A withdrawal request can be created only after the Merchant ID, registered website domain, API Key and Secret Key are verified against an active Merchant Panel. After authentication, the requested gross amount moves from available balance to pending balance and the API returns a unique pending transaction.

Use the standard signed request headers

Withdraw, status and balance endpoints require the same Merchant ID, registered domain, API Key, timestamp, nonce and HMAC-SHA256 signature format as the Deposit API.

$merchantId = 'SENDBOX123456';
$merchantDomain = 'merchant.example.com';
$body = json_encode($payload, JSON_UNESCAPED_SLASHES);
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(16));
$signature = hash_hmac(
    'sha256',
    $merchantId . "\n" . $merchantDomain . "\n" . $timestamp . "\n" . $nonce . "\n" . $body,
    'YOUR_API_SECRET'
);

Submit a withdrawal request

Request example

{
  "order_id": "WD-10001",
  "amount": "1000.00",
  "payment_method": "BKASH",
  "account_number": "01712345678",
  "account_name": "Recipient Name",
  "callback_url": "https://merchant.example.com/webhooks/sendboxpay"
}

Success response · HTTP 201

{
  "success": true,
  "order_id": "WD-10001",
  "amount": "1000.00",
  "charge": "15.00",
  "net_amount": "985.00",
  "status": "pending",
  "message": "Withdrawal request created successfully."
}

Query a withdrawal

{
  "order_id": "WD-10001"
}

{
  "success": true,
  "withdrawal": {
    "reference": "WD-10001",
    "gross_amount": "1000.00",
    "charge_amount": "15.00",
    "net_amount": "985.00",
    "status": "pending",
    "description": "Withdrawal request created through API.",
    "completed_at": null,
    "created_at": "2026-07-16 14:40:00"
  }
}

Read merchant balance

Send an empty JSON object and sign the exact body {}.

{}

{
  "success": true,
  "balance": {
    "available_balance": "15000.00",
    "pending_balance": "1000.00",
    "total_deposit": "22000.00",
    "total_withdraw": "6000.00",
    "updated_at": "2026-07-16 14:40:00"
  }
}

Verify withdrawal events

After a withdrawal request is accepted, SendboxPay sends a signed withdrawal.created event to the configured callback URL. Verify the signature before storing the event.

{
  "event": "withdrawal.created",
  "sent_at": "2026-07-16T08:40:00+00:00",
  "data": {
    "order_id": "WD-10001",
    "status": "pending",
    "amount": "1000.00",
    "charge": "15.00",
    "net_amount": "985.00",
    "currency": "BDT",
    "payment_method": "bKash",
    "account_number": "017****5678",
    "account_name": "Recipient Name"
  }
}

Node.js webhook verification

import crypto from 'node:crypto';
import express from 'express';

const app = express();
app.post('/webhooks/sendboxpay', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.header('X-SBP-Timestamp') || '';
  const received = (req.header('X-SBP-Signature') || '').toLowerCase();
  const rawBody = req.body.toString('utf8');
  const expected = crypto
    .createHmac('sha256', process.env.SENDBOXPAY_API_SECRET)
    .update(`${timestamp}\n${rawBody}`)
    .digest('hex');

  if (!/^\d+$/.test(timestamp)
      || Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > 300
      || received.length !== expected.length
      || !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(rawBody);
  // Store and process the event idempotently.
  return res.status(200).send('OK');
});

HTTP status and common failures

{
  "success": false,
  "message": "Insufficient available balance."
}

Withdrawal protection requirements

Framework examples

<?php
$payload = [
    'order_id' => 'WD-' . time(),
    'amount' => '1000.00',
    'payment_method' => 'BKASH',
    'account_number' => '01712345678',
    'account_name' => 'Recipient Name',
    'callback_url' => 'https://merchant.example.com/webhooks/sendboxpay',
];
$merchantId = getenv('SENDBOXPAY_MERCHANT_ID');
$merchantDomain = getenv('SENDBOXPAY_MERCHANT_DOMAIN');
$body = json_encode($payload, JSON_UNESCAPED_SLASHES);
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(16));
$signature = hash_hmac('sha256', $merchantId . "\n" . $merchantDomain . "\n" . $timestamp . "\n" . $nonce . "\n" . $body, getenv('SENDBOXPAY_API_SECRET'));

$ch = curl_init('https://www.sendboxpay.cyou/api/v1/withdraw/create.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-SBP-Merchant-ID: ' . $merchantId,
        'X-SBP-Merchant-Domain: ' . $merchantDomain,
        'X-SBP-API-Key: ' . getenv('SENDBOXPAY_API_KEY'),
        'X-SBP-Timestamp: ' . $timestamp,
        'X-SBP-Nonce: ' . $nonce,
        'X-SBP-Signature: ' . $signature,
    ],
]);
$response = curl_exec($ch);
curl_close($ch);

$payload = [
    'order_id' => 'WD-' . now()->timestamp,
    'amount' => '1000.00',
    'payment_method' => 'BKASH',
    'account_number' => '01712345678',
    'account_name' => 'Recipient Name',
];
$merchantId = config('services.sendboxpay.merchant_id');
$merchantDomain = config('services.sendboxpay.domain');
$body = json_encode($payload, JSON_UNESCAPED_SLASHES);
$timestamp = (string) time();
$nonce = Str::random(32);
$signature = hash_hmac('sha256', $merchantId . "\n" . $merchantDomain . "\n" . $timestamp . "\n" . $nonce . "\n" . $body, config('services.sendboxpay.secret'));

$response = Http::withBody($body, 'application/json')
    ->withHeaders([
        'X-SBP-Merchant-ID' => $merchantId,
        'X-SBP-Merchant-Domain' => $merchantDomain,
        'X-SBP-API-Key' => config('services.sendboxpay.key'),
        'X-SBP-Timestamp' => $timestamp,
        'X-SBP-Nonce' => $nonce,
        'X-SBP-Signature' => $signature,
    ])
    ->post('https://www.sendboxpay.cyou/api/v1/withdraw/create.php')
    ->throw()
    ->json();

import crypto from 'node:crypto';

const payload = {
  order_id: `WD-${Date.now()}`,
  amount: '1000.00',
  payment_method: 'BKASH',
  account_number: '01712345678',
  account_name: 'Recipient Name'
};
const merchantId = process.env.SENDBOXPAY_MERCHANT_ID;
const merchantDomain = process.env.SENDBOXPAY_MERCHANT_DOMAIN;
const body = JSON.stringify(payload);
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomBytes(16).toString('hex');
const signature = crypto
  .createHmac('sha256', process.env.SENDBOXPAY_API_SECRET)
  .update(`${merchantId}\n${merchantDomain}\n${timestamp}\n${nonce}\n${body}`)
  .digest('hex');

const response = await fetch('https://www.sendboxpay.cyou/api/v1/withdraw/create.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-SBP-Merchant-ID': merchantId,
    'X-SBP-Merchant-Domain': merchantDomain,
    'X-SBP-API-Key': process.env.SENDBOXPAY_API_KEY,
    'X-SBP-Timestamp': timestamp,
    'X-SBP-Nonce': nonce,
    'X-SBP-Signature': signature
  },
  body
});