Quickstart Guide

RumhoPay Merchant Integration

Integrate secure bKash, Nagad, and Rocket automated payments into your website (PHP, WordPress, WooCommerce, Laravel, Node.js) or mobile app (Flutter, React Native, Android, iOS) with a single unified API.

How it works: Your server sends a payment request to RumhoPay → receives a hosted checkout paymentUrl → redirects customer to pay → RumhoPay automatically validates SMS via Android companion app → fires an instant Webhook to confirm order!

3-Step Integration Flow:

Obtain API Credentials: Get your X-API-KEY and X-API-SECRET from the RumhoPay Admin.
Initiate Charge: Send a POST request with order details to /api/v1/checkout/create-charge.
Redirect & Receive: Redirect user to paymentUrl, then listen for RumhoPay's instant webhook callback on your server.

Security

Authentication

Every request to the RumhoPay API must include your merchant credentials in the HTTP request headers:

Header Key	Type	Description
`X-API-KEY`	String	Your merchant live API Key (e.g. `rumho_live_af92cc0915004c0f`)
`X-API-SECRET`	String	Your secret key (e.g. `sec_08c4...`). Never expose this in client-side code!
`Content-Type`	String	Must be `application/json`

Endpoint

Create Payment Charge

Create a new hosted checkout session and receive a payment URL for your customer.

POST https://pay.rumho.com/api/v1/checkout/create-charge

Request Body Parameters:

Parameter	Type	Requirement	Description
`amount`	Number	Required	The total amount to charge in BDT (e.g. `500`).
`storeName`	String	Optional	Your custom store or brand name displayed to customers on the checkout page (e.g. `"Fashion BD"`, `"Mathbaria Shop"`). Defaults to your API Key name.
`storeLogo`	String (URL)	Optional	Direct HTTPS image URL of your brand logo (e.g. `"https://myshop.com/logo.png"`) to display on the checkout page.
`currency`	String	Optional	Currency code. Defaults to `BDT`.
`customerName`	String	Optional	Name of customer for receipt and invoice display.
`customerEmail`	String	Optional	Customer email address.
`customerPhone`	String	Optional	Customer mobile phone number.
`description`	String	Optional	Order summary or invoice title (e.g. `Order #9821`).
`successUrl`	String	Recommended	URL customer will be redirected to after successful payment.
`cancelUrl`	String	Optional	URL customer will be returned to if they cancel payment.
`webhookUrl`	String	Recommended	Your server endpoint to receive asynchronous IPN payment confirmation.

Sample Success Response (201 Created):

{
  "status": true,
  "message": "Payment session created successfully",
  "paymentUrl": "https://pay.rumho.com/checkout/RP-20261025-A1B2",
  "invoiceId": "ef8fff21-60cb-4223-8066-1d4480de2411",
  "invoiceNumber": "RP-20261025-A1B2",
  "amount": 500,
  "currency": "BDT",
  "expiresAt": "2026-10-25T16:30:00.000Z"
}

Implementation

Ready-to-Use Code Samples

Select your programming language or framework to see how to initiate a payment:

<?php
$curl = curl_init();

$postData = [
    'amount'        => 500,
    'currency'      => 'BDT',
    'customerName'  => 'Karim Ahmed',
    'customerEmail' => 'karim@gmail.com',
    'customerPhone' => '01700000000',
    'description'   => 'Order #1042',
    'successUrl'    => 'https://myshop.com/payment-success',
    'cancelUrl'     => 'https://myshop.com/payment-cancel',
    'webhookUrl'    => 'https://myshop.com/api/rumhopay-webhook'
];

curl_setopt_array($curl, [
    CURLOPT_URL => "https://pay.rumho.com/api/v1/checkout/create-charge",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($postData),
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "X-API-KEY: YOUR_API_KEY_HERE",
        "X-API-SECRET: YOUR_API_SECRET_HERE"
    ],
]);

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

$result = json_decode($response, true);

if (!empty($result['status']) && !empty($result['paymentUrl'])) {
    // Redirect customer to RumhoPay checkout:
    header("Location: " . $result['paymentUrl']);
    exit;
} else {
    echo "Payment creation failed: " . ($result['message'] ?? 'Error');
}
?>

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<String?> createRumhoPayment({
  required double amount,
  required String customerName,
  required String customerPhone,
}) async {
  final url = Uri.parse('https://pay.rumho.com/api/v1/checkout/create-charge');

  final response = await http.post(
    url,
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': 'YOUR_API_KEY_HERE',
      'X-API-SECRET': 'YOUR_API_SECRET_HERE',
    },
    body: jsonEncode({
      'amount': amount,
      'currency': 'BDT',
      'customerName': customerName,
      'customerPhone': customerPhone,
      'description': 'Mobile App Order',
      'successUrl': 'https://myshop.com/payment-success',
      'cancelUrl': 'https://myshop.com/payment-cancel',
      'webhookUrl': 'https://myshop.com/api/rumhopay-webhook',
    }),
  );

  final data = jsonDecode(response.body);
  if (data['status'] == true && data['paymentUrl'] != null) {
    // Open this URL inside your in-app WebView
    return data['paymentUrl'];
  }
  return null;
}

// Using Node.js Native Fetch (Node 18+)
const response = await fetch('https://pay.rumho.com/api/v1/checkout/create-charge', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_API_KEY_HERE',
    'X-API-SECRET': 'YOUR_API_SECRET_HERE'
  },
  body: JSON.stringify({
    amount: 500,
    currency: 'BDT',
    customerName: 'Karim Ahmed',
    customerEmail: 'karim@gmail.com',
    customerPhone: '01700000000',
    description: 'Order #1042',
    successUrl: 'https://myshop.com/payment-success',
    cancelUrl: 'https://myshop.com/payment-cancel',
    webhookUrl: 'https://myshop.com/api/rumhopay-webhook'
  })
});

const data = await response.json();
if (data.status) {
  // Redirect customer
  window.location.href = data.paymentUrl;
}

import requests

url = "https://pay.rumho.com/api/v1/checkout/create-charge"

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "YOUR_API_KEY_HERE",
    "X-API-SECRET": "YOUR_API_SECRET_HERE"
}

payload = {
    "amount": 500,
    "currency": "BDT",
    "customerName": "Karim Ahmed",
    "customerEmail": "karim@gmail.com",
    "customerPhone": "01700000000",
    "description": "Order #1042",
    "successUrl": "https://myshop.com/payment-success",
    "cancelUrl": "https://myshop.com/payment-cancel",
    "webhookUrl": "https://myshop.com/api/rumhopay-webhook"
}

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

if data.get("status"):
    print("Redirect customer to:", data.get("paymentUrl"))

curl -X POST https://pay.rumho.com/api/v1/checkout/create-charge \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY_HERE" \
  -H "X-API-SECRET: YOUR_API_SECRET_HERE" \
  -d '{
    "amount": 500,
    "currency": "BDT",
    "customerName": "Karim Ahmed",
    "customerPhone": "01700000000",
    "description": "Order #1042",
    "successUrl": "https://myshop.com/payment-success",
    "webhookUrl": "https://myshop.com/api/rumhopay-webhook"
  }'

Automation

Webhook IPN Callback

When a customer sends money and the SMS is matched, RumhoPay sends a server-to-server POST request to your webhookUrl to automatically mark orders as paid.

Webhook Payload Sample:

{
  "event": "payment.completed",
  "invoiceId": "ef8fff21-60cb-4223-8066-1d4480de2411",
  "invoiceNumber": "RP-20261025-A1B2",
  "amount": 500,
  "currency": "BDT",
  "paymentMethod": "BKASH_PERSONAL",
  "trxId": "BL29X94KL1",
  "senderNumber": "017XXXXXXXX",
  "paidAt": "2026-10-25T16:15:30.000Z",
  "status": "COMPLETED"
}

Webhook Best Practice: Return an HTTP 200 OK status code upon receiving the webhook to notify RumhoPay that your store processed the notification.

Verification

Verify Payment Status

You can query the status of any invoice at any time using its invoice ID or invoice number.

GET https://pay.rumho.com/api/v1/checkout/verify-charge/:invoiceNumber

Sample Response:

{
  "status": true,
  "invoice": {
    "invoiceNumber": "RP-20261025-A1B2",
    "status": "COMPLETED",
    "amount": 500,
    "trxId": "BL29X94KL1",
    "paidAt": "2026-10-25T16:15:30.000Z"
  }
}