NAGAD API v3.3

Developer Portal & Reference

Code Snippets
Official Standard Integration Guide

Nagad Online Payment Gateway API

নগদ পেমেন্ট গেটওয়ে ইন্টিগ্রেশনের সম্পূর্ণ সুস্পষ্ট ও সহজবোধ্য ডকুমেন্টেশন। bKash ডেভলপার পোর্টালের মতো প্রতিটি স্টেপ, RSA এনক্রিপশন/ডিক্রিপশন, রিয়েল কোড এক্সাম্পল (JavaScript, PHP, Laravel, Python, Java) সহ সাজানো।

Dual-Key Cryptography

Nagad uses RSA PKCS1Padding for encryption and SHA1withRSA for digital signatures with Base64 payload encoding.

2-Step Checkout Flow

1. Initialize: Generates unique PaymentRefId & Challenge.
2. Place Order: Passes order amount and returns Nagad redirect URL.

Callback & Server Verify

Instant redirect callback to merchant site, followed by a mandatory server-to-server Verification API call to validate payment legitimacy.

1

Payment Architecture & Call Flow

Nagad Online Payment Gateway follows a secure, stateless HTTPS REST model. The entire payment lifecycle consists of the following seamless flow:

Customer / Browser
Merchant Server (Backend)
Nagad Gateway Server
Nagad UI / OTP Engine
1
User clicks "Pay with Nagad" → Customer triggers checkout on merchant storefront.
Storefront
2
Initialize API Call: Merchant backend encrypts sensitive data with Nagad Public Key and signs with Merchant Private Key, sending POST to Nagad.
POST /initialize
3
Nagad responds with PaymentReferenceId & Challenge → Merchant decrypts with Merchant Private Key and verifies signature.
JSON Response
4
Place Order API Call: Merchant backend sends amount, challenge, callbackURL to Nagad.
POST /complete
5
Nagad returns callBackUrl: Merchant redirects customer browser to this Nagad hosted payment page.
Redirect 302
6
Customer Enters Mobile No + OTP + PIN: Handled securely on Nagad's portal.
Nagad Hosted UI
7
Redirect Back + Server Verification: Nagad redirects customer back to merchantCallbackURL with status. Merchant backend calls GET /verify/payment/{paymentRefId} to confirm payment status.
GET /verify
2

Merchant Onboarding (4 Steps)

1

Register as a Merchant

Register in the Nagad Merchant Portal with your business information, trade license, bank account, and server IP details.

2

Get Merchant Credentials

From the merchant portal dashboard, obtain your assigned Merchant ID (e.g. 687450000031324) and download Nagad Gateway Public Key.

3

Generate & Upload Keys

Generate your own 2048-bit Merchant RSA Key Pair. Upload your Public Key to the Nagad Merchant Portal, and keep your Private Key confidential on your server.

4

Integrate APIs

Implement the 3 core APIs: Initialize Order, Place Order, and Verify Payment using our ready-made SDK examples in PHP, Laravel, Node.js, Python, or Java.

3

Environments & Base URLs

Environment Base URL Port Context Path Status
Sandbox (Testing) http://sandbox.mynagad.com 10080 / 12345 remote-payment-gateway-1.0 Testing only
Production (Live) https://api.mynagad.com Default (443) remote-payment-gateway-1.0 Live Accounts

Standard URL Structure:
{BASE_URL}:{PORT}/{CONTEXT_PATH}/{API_PATH}

Example Initialize Endpoint:
http://sandbox.mynagad.com:10080/remote-payment-gateway-1.0/api/dfs/check-out/initialize/{merchantId}/{orderId}

4

Standard HTTP Request Headers

Every HTTP request sent to Nagad Payment Gateway must include these mandatory meta-data headers:

Header Key Required Type Allowed / Example Values Description
X-KM-IP-V4 Mandatory String "103.100.12.34" Client / Customer public IPv4 address.
X-KM-Client-Type Mandatory String PC_WEB | MOBILE_WEB | MOBILE_APP | WALLET_WEB_VIEW | BILL_KEY Device/Client platform initiating the transaction.
X-KM-Api-Version Mandatory String "v-0.2.0" or "v-3.0.1" API protocol version (use v-0.2.0 for standard, v-3.0.1 for sender fee).
Content-Type Mandatory String application/json Payload encoding format for POST requests.
5

Purchase Status States

Success Payment charged successfully. (Final)
OrderInitiated Order session initialized.
InProgress Customer on payment page.
OtpSent OTP sent to customer SIM.
OtpVerified OTP verified by user.
PinGiven PIN entered, processing.
Cancelled User cancelled the transaction.
Failed Transaction declined/failed.
Aborted User closed page or timed out.
InvalidRequest Payload verification failed.
Fraud Flagged by risk engine.
UnknownFailed Unexpected system error.
Next Chapter

Compare bKash vs Nagad Architecture

View bKash vs Nagad Comparison