bKash Payment Gateway Integration Tutorial 2026

Understanding the bKash Payment Gateway API

The bKash Payment Gateway (PGW) API enables merchants to accept payments directly on their websites and mobile applications. Unlike collecting payments through a personal bKash number — which violates bKash terms of service and exposes you to fraud — the official API provides a secure, automated checkout experience with real-time transaction verification.

bKash offers two primary integration models. The Checkout model redirects customers to a bKash-hosted payment page where they authorize the transaction using their PIN. The Tokenized model allows returning customers to pay with a single tap by saving their wallet information securely. Both models use REST API endpoints with OAuth 2.0 token-based authentication, ensuring that every request is verified before processing.

The API follows a straightforward flow: your server requests a grant token, creates a payment with the amount and invoice details, redirects the user to bKash for authorization, and then executes the payment upon receiving a success callback. Each step is logged and verifiable, providing a complete audit trail for reconciliation. For businesses building e-commerce platforms, this level of transparency is essential.

Merchant Account Requirements

Before writing a single line of code, you need a bKash merchant account. This is a non-negotiable requirement — the API credentials are only issued to approved merchants. The application process requires several documents and typically takes one to three weeks for verification.

• Trade License: A valid, up-to-date trade license issued by your local city corporation or municipality. bKash verifies the license number against government records.
• TIN Certificate: Your Tax Identification Number certificate is required for merchant verification and tax compliance purposes.
• Bank Account Details: A business bank account where bKash will settle your funds. Settlements typically happen within 1 to 3 business days after a transaction.
• NID Copy: A photocopy of the business owner's National ID card for identity verification.
• Website URL: A live or staging URL of the website where you plan to accept payments. bKash reviews the site to ensure it meets their merchant guidelines.

Once approved, bKash provides you with four critical credentials: an App Key, an App Secret, a Username, and a Password. These are environment-specific — you receive separate credentials for the sandbox and production environments. Store these securely in environment variables and never commit them to version control.

Setting Up the Sandbox Environment

The bKash sandbox is a test environment that mirrors production behavior without processing real money. It is essential for development and quality assurance. The sandbox base URL is different from the production URL, and bKash provides test wallet numbers and OTPs for simulating transactions.

Start by configuring your development environment with the sandbox credentials. Create environment variables for the base URL, app key, app secret, username, and password. Your server-side code should read these variables at runtime so you can switch between sandbox and production by changing a single configuration file — not by modifying code.

In the sandbox, test every possible scenario: successful payments, failed payments, user cancellations, network timeouts, and duplicate payment attempts. The sandbox allows you to trigger these scenarios using specific test amounts and wallet numbers provided in the bKash developer documentation. Document each test case and its expected outcome. This rigorous testing in sandbox saves hours of debugging in production and prevents real financial losses.

Step-by-Step Integration Workflow

The bKash payment gateway integration follows a five-step workflow that your backend server orchestrates. Understanding each step is critical for building a reliable payment flow.

Step 1 — Grant Token: Your server sends a POST request to the bKash token endpoint with your app key, app secret, username, and password. bKash returns a time-limited access token (typically valid for 60 minutes) that authenticates all subsequent API calls. Cache this token and refresh it before expiry to avoid unnecessary token requests.

Step 2 — Create Payment: Using the grant token, your server sends a payment creation request with the amount, currency (BDT), invoice number, and callback URLs for success and failure. bKash returns a payment ID and a redirect URL. Store the payment ID in your database linked to the order.

Step 3 — Redirect User: Your frontend redirects the customer to the bKash URL where they enter their wallet number and PIN to authorize the payment. This step happens entirely on bKash's secure domain — your website never handles the customer's bKash credentials.

Step 4 — Execute Payment: After the customer authorizes the payment, bKash redirects them back to your success callback URL with a payment ID and status. Your server then calls the bKash execute payment endpoint to finalize the transaction. This two-step confirmation prevents unauthorized executions.

Step 5 — Query Payment: After execution, call the query payment endpoint to verify the final transaction status. Compare the amount, transaction ID, and status against your records. Update your order status in the database only after this verification step confirms a successful payment.

Production Deployment Checklist

Moving from sandbox to production is not simply a matter of swapping API keys. You need to verify several critical aspects before accepting real payments from customers.

• SSL Certificate: Your website must use HTTPS. bKash will reject callback requests to non-HTTPS URLs. Use a certificate from Let's Encrypt or your hosting provider.
• Server-Side Validation: Never trust client-side data alone. Always verify payment amounts, transaction IDs, and statuses on your server by calling the bKash query API.
• Idempotency: Ensure your payment execution endpoint handles duplicate requests gracefully. Network issues can cause callback URLs to be hit multiple times.
• Error Handling: Implement comprehensive error handling for every API call. Log errors with sufficient detail for debugging but never log sensitive credentials.
• Monitoring & Alerts: Set up monitoring for failed transactions, timeout rates, and unusual patterns. Alerting helps you catch issues before they affect many customers.
• Reconciliation: Build a daily reconciliation process that compares your transaction records with bKash settlement reports to catch discrepancies early.

Before going live, submit your integration for bKash review. They will test a series of transactions on your staging environment and verify that your implementation meets their security and UX standards. Approval typically takes 2 to 5 business days.

Security Best Practices

Payment integrations are high-value targets for attackers. A single vulnerability can result in financial losses and loss of customer trust. Follow these security best practices to protect your bKash integration.

Never expose credentials client-side. All bKash API calls must happen on your server. Your app key, app secret, username, and password should live in server-side environment variables, never in JavaScript bundles or HTML source code. Use a professional web development approach with proper backend architecture.

Validate callback signatures. When bKash redirects a customer back to your website, verify that the callback data is authentic. Cross-reference the payment ID, amount, and status with your database records and the bKash query API. This prevents attackers from forging successful payment callbacks.

Implement rate limiting. Protect your payment endpoints from abuse by limiting the number of requests per IP address and per user session. This prevents brute-force attacks and reduces the risk of DDoS targeting your payment infrastructure.

Use webhook verification. If you use bKash IPN (Instant Payment Notification) webhooks, verify the source IP against bKash's published IP whitelist. Reject any webhook requests from unauthorized sources. Log all webhook payloads for audit purposes.

Common Errors and Troubleshooting

During bKash payment gateway integration, developers frequently encounter a set of common errors. Understanding these issues saves significant debugging time.

• Token Expired (2023): The grant token has a limited lifespan. Implement automatic token refresh logic that requests a new token before the current one expires.
• Invalid App Key (2001): Double-check your credentials. Sandbox and production use different app keys. Ensure you are using the correct set for your environment.
• Amount Mismatch: The amount sent in the create payment request must exactly match the amount in the execute request. Even a one-paisa difference will cause a failure.
• Callback URL Mismatch: The callback URLs registered with bKash must match exactly what your server sends. Trailing slashes, HTTP vs HTTPS, and port numbers all matter.
• Duplicate Transaction ID: Each invoice number must be unique. Reusing an invoice number from a previous transaction will result in an error. Use a combination of order ID and timestamp to generate unique invoice numbers.

Why DIPTAIT for bKash Integration

Integrating the bKash payment gateway correctly requires backend expertise, security awareness, and attention to edge cases that only come with experience. At DIPTAIT, we have integrated bKash payments across multiple e-commerce projects and custom web applications for businesses across Bangladesh.

Our integration service covers everything: merchant account registration guidance, complete API integration with your existing platform, thorough sandbox and production testing, security hardening, and post-launch monitoring setup. We use modern technologies like Next.js and Supabase to build payment flows that are fast, secure, and maintainable long-term.

Whether you are building a new e-commerce store or adding bKash to an existing website, our team handles the complexity so you can focus on growing your business. We also integrate Nagad, SSLCommerz, and card payment gateways alongside bKash for a complete payment solution.