Skip to content

Bangladesh (Mobile Wallets) H2H Integration

This guide covers H2H payment integration for Bangladesh using mobile wallets (BKASH and NAGAD). These wallets are the primary digital payment methods in Bangladesh.

Overview

Currency: BDT (Bangladeshi Taka)
Payment Methods: BKASH, NAGAD
Languages: Bengali (BN), English (EN)
User Experience: Customer redirected to official wallet payment page

Payment Flow

  1. Initiate Payment: Call /h2h/initiate with BDT currency and wallet selection
  2. Display Payment URL: Show payment button or QR code linking to wallet page
  3. Customer Redirected: Customer goes to official BKASH or NAGAD payment page
  4. Customer Pays: Customer completes payment in their wallet
  5. Confirmation: Payment status varies by wallet, may require proof submission

HTTP Request

POST http://{{DOMAIN}}/h2h/initiate

Request Example

curl -X POST https://{{DOMAIN}}/h2h/initiate \
-H "Content-Type: application/json" \
-d '{
  "public_key": "your_api_key",
  "amount": 200.00,
  "currency": "BDT",
  "payment_method_type": "local",
  "customer": {
      "first_name": "Mohammad",
      "last_name": "Rahman",
      "email": "[email protected]",
      "mobile": "+8801700000000",
      "payment_method_code": "NAGAD",
      "language": "BN"
  },
  "details": "Payment for order #123",
  "identifier": "order_123_unique_id",
  "ipn_url": "https://yourdomain.com/ipn",
  "success_url": "https://yourdomain.com/success",
  "cancel_url": "https://yourdomain.com/cancel",
  "site_name": "Your Store"
}'

Response Example

{
  "status": "success",
  "trx": "UUID",
  "paymentlinks": {
    "nagad": "https://nagad.com.bd/pay?token=xyz123&amount=200.00"
  },
  "payment_method_code": "BKASH",
  "language": "EN"
}

Request Parameters

Parameter Required Description Example
public_key true Your API key "your_api_key"
amount true Amount in BDT (minimum varies by wallet) 200.00, 500.00
currency true Must be "BDT" for Bangladesh "BDT"
payment_method_type true Must be "local" for Bangladesh wallets "local"
customer true Customer information with Bangladesh-specific fields See Customer Parameters
details true Payment description (max 255 chars) "Payment for order #123"
identifier true Unique payment ID (max 255 chars) "order_123_unique_id"
ipn_url true Webhook URL for status updates "https://yourdomain.com/ipn"
success_url true Success redirect URL "https://yourdomain.com/success"
cancel_url true Cancel redirect URL "https://yourdomain.com/cancel"
site_name true Your website name "Your Store"
site_logo false Your logo URL "https://yourdomain.com/logo.png"

Customer Parameters

Parameter Required Description Example
first_name true Customer's first name "Mohammad"
last_name true Customer's last name "Rahman"
email true Customer's email address "[email protected]"
mobile true Bangladeshi mobile number "+8801700000000"
payment_method_code false Use specific wallet (BKASH or NAGAD). Case-insensitive. "NAGAD", "BKASH"
language false Interface language. Case-insensitive. "BN" (Bengali), "EN" (English)

Country-Specific Parameters

payment_method_code (Optional)

  • Purpose: Use selection of specific mobile wallet
  • Values:
  • "BKASH" - Use BKASH wallet
  • "NAGAD" - Use NAGAD wallet
  • Default: Platform default (usually BKASH unless configured otherwise)

language (Optional)

  • Purpose: Set the payment interface language
  • Values:
  • "BN" - Bengali interface
  • "EN" - English interface
  • Default: English (EN) if not provided

Parameter Scope

Bangladesh-specific parameters only work when currency is "BDT". They have no effect for other currencies.

Response Parameters

Parameter Description Example
status Request status "success"
trx Transaction ID for status checking "UUID"
paymentlinks Wallet-specific payment URLs See Payment Links section
payment_method_code Wallet selected for payment "BKASH"
language Payment interface language "EN"

The response contains URLs for the selected mobile wallet:

Link Type Description When Available
bkash BKASH wallet payment URL When BKASH is selected/default
nagad NAGAD wallet payment URL When NAGAD is selected

What to Expect

Payment Confirmation

  • Automatic: Most of the payments confirm automatically
  • Manual Verification: There is a fallback flow for the case if some payments require proof submission
  • Timing: Usually within 10-20 seconds. Varies by wallet and network conditions
  • Proof Process: Customer submits screenshot → manual review (5-30 minutes)

User Experience Flow

  1. Customer clicks payment button on your site
  2. New tab/window opens with customer's wallet payment page
  3. Customer logs into their wallet and confirms payment
  4. Customer returns to your site
  5. Your system monitors payment status
  6. If needed, customer provides payment proof

Error Handling

Common Error Responses

{
  "status": "error",
  "message": ["No H2H flows available for this currency and merchant"]
}

Error Scenarios

  • Currency Mismatch: Ensure currency is "BDT"
  • Invalid Wallet Code: Use "BKASH" or "NAGAD" exactly
  • Merchant Not Enabled: Contact support to enable Bangladesh H2H

Best Practices

User Experience

  1. Clear Instructions: Explain the redirect process to customers
  2. Wallet Branding: Use official wallet logos and colors
  3. Language Support: Offer Bengali interface for local customers
  4. Progress Indicators: Show payment status while monitoring
  5. Fallback Handling: Prepare for manual verification scenarios

Technical Implementation

  1. Status Monitoring: Implement status polling
  2. Proof Handling: Build UI for proof submission
  3. IPN Integration: Set up webhook handling
  4. Mobile Optimization: Ensure mobile-friendly wallet redirection

Next Steps