NAGAD API v3.3

Developer Portal & Reference

Step 1 of 3
POST /remote-payment-gateway-1.0/api/dfs/check-out/initialize/{merchantId}/{orderId}

Initialize Payment Session

এই API-এর মাধ্যমে নগদ গেটওয়েতে একটি নতুন পেমেন্ট সেশন শুরু হয়। Nagad রেসপন্সে একটি এনক্রিপ্টেড paymentReferenceId এবং challenge পাঠায় যা পরবর্তী Place Order API কলের জন্য বাধ্যতামূলক।

POST https://{NAGAD_HOST}/remote-payment-gateway-1.0/api/dfs/check-out/initialize/{merchantId}/{orderId}?locale=BN
Content-Type: application/json

Request Headers

Header Requirement Example Value Description
X-KM-IP-V4 Mandatory "103.100.12.34" End-user IP address.
X-KM-Client-Type Mandatory "PC_WEB" Client channel: PC_WEB, MOBILE_WEB, MOBILE_APP
X-KM-Api-Version Mandatory "v-0.2.0" Protocol version (standard: v-0.2.0).
Content-Type Mandatory "application/json" JSON request body.

Parameters Specification

Type Name Data Type Req Length Description
Path merchantId String M 15 Merchant Account ID from Nagad Portal.
Path orderId AlphaNumeric M 5~20 Unique invoice/order identifier for this transaction.
Query locale String O 2 Default language: EN or BN (default is EN).
Body dateTime Numeric String M 14 Timestamp format: yyyyMMddHHmmss (e.g. 20260909120000).
Body sensitiveData Base64 String M 1~1024 Encrypted sensitive payload using Nagad Public Key.
Body signature Base64 String M 1~1024 SHA1withRSA signature using Merchant Private Key.
Body accountNumber Numeric String O 11 Merchant mobile account number if applicable.

Data Elements inside Plain sensitiveData:

এনক্রিপ্ট করার আগে এই ৪টি ফিল্ড সংবলিত একটি JSON তৈরি করতে হবে:

{
  "merchantId": "687450000031324",
  "datetime": "20260909120000",
  "orderId": "ORD123456",
  "challenge": "695EF3869547B6C07F5D56399935FB72D21737EA"
}
  • challenge: একটি 40-character হেক্সাডেসিমেল র‍্যান্ডম স্ট্রিং (e.g. 20 random bytes in hex).
  • datetime: সার্ভারের বর্তমান সময় yyyyMMddHHmmss ফরম্যাটে।

Runnable Code Examples (Initialize Order)

curl -X POST "http://sandbox.mynagad.com:10080/remote-payment-gateway-1.0/api/dfs/check-out/initialize/687450000031324/ORD123456?locale=BN" \
  -H "X-KM-IP-V4: 103.100.12.34" \
  -H "X-KM-Client-Type: PC_WEB" \
  -H "X-KM-Api-Version: v-0.2.0" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "01745000003",
    "dateTime": "20260909120000",
    "sensitiveData": "G58zmiHNIT+CM74fQyL6+w0WdPXioW6oZy1piRABi1ssj3vt89LZoLPh/...",
    "signature": "AlhsvF6ZdEUbDqXeeHeS6Ab9e+/W8U4pxZjMr5+qx5aGIDj21R6qGiYFiHm9..."
  }'

Response Structure & Decryption

1. Raw Encrypted Response from Nagad
{
  "sensitiveData": "C5aETMhx5UexvlO0fSNN9YFWwCSJrRO4...",
  "signature": "hD2RD8ZKUhBjKTnwnvS+pF2vWrOTTOfw..."
}
2. Decrypted Plain JSON (with Private Key)
{
  "paymentReferenceId": "MTEwNzE2NTMxODgwNC42ODc0N...",
  "challenge": "40C88FFFF3274CD3698B140E7F7C211C...",
  "acceptDateTime": "20260909120005"
}
Next Action: Store the paymentReferenceId and returned challenge in your session or cache, and immediately call Place Order API.