পেমেন্ট গেটওয়ে API ডকুমেন্টেশন

ইন্টিগ্রেশন ধাপ

গেটওয়ে API ব্যবহারের আগে মার্চেন্ট প্যানেলের API বিভাগে সফল, ব্যর্থ, বাতিল এবং Webhook—এই চারটি URL সংরক্ষণ করা বাধ্যতামূলক। পেমেন্ট তৈরির অনুরোধে URL পাঠাতে হয় না; সংরক্ষিত URL স্বয়ংক্রিয়ভাবে ব্যবহৃত হয়।

৪টি URL সংরক্ষণ Access Token পেমেন্ট তৈরি অবস্থা যাচাই Webhook গ্রহণ

রিটার্ন ও Webhook URL

মার্চেন্ট প্যানেলের API কী ও ইন্টিগ্রেশন পৃষ্ঠায় নিচের চারটি URL সংরক্ষণ করুন। চারটি URL সম্পূর্ণ না থাকলে নতুন গেটওয়ে পেমেন্ট সেশন তৈরি হবে না।

সফল URLhttps://your-domain.com/payment/success

ব্যর্থ URLhttps://your-domain.com/payment/failed

বাতিল URLhttps://your-domain.com/payment/cancel

Webhook URLhttps://your-domain.com/payment/webhook

অনুরোধে URL পাঠাবেন নাsuccess_url, failed_url, cancel_url এবং webhook_url পেমেন্ট তৈরির JSON-এ প্রয়োজন নেই।

পেমেন্ট অনুরোধে থাকবে না

{
  "tran_id": "ORDER-1001",
  "amount": 100,
  "currency": "BDT",
  "customer_name": "Customer Name",
  "customer_mobile": "017XXXXXXXX",
  "customer_email": "customer@example.com",
  "description": "Order payment"
}

Access Token তৈরি

POSThttps://smartservices-icps-gov.com/api/v1/gateway/token

API কী ও ৫ সংখ্যার মার্চেন্ট পিন দিয়ে ১৫ মিনিটের Bearer Access Token নিন। পেমেন্ট তৈরি ও অবস্থা যাচাইয়ের সময় এই টোকেন ব্যবহার করুন।

অনুরোধ

{
  "api_key": "nict_live_YOUR_API_KEY",
  "pin": "12345"
}

সফল উত্তর

{
  "success": true,
  "data": {
    "access_token": "nict_at_xxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 900
  }
}

পেমেন্ট তৈরি

POSThttps://smartservices-icps-gov.com/api/v1/gateway/payments

একটি অনন্য tran_id এবং পেমেন্টের তথ্য পাঠান। সফল উত্তরে payment_url পাওয়া যাবে। গ্রাহককে সেই URL-এ পাঠান।

ফিল্ড	বিবরণ
`tran_id`	আপনার সিস্টেমের অনন্য লেনদেন নম্বর।
`amount`	পেমেন্টের পরিমাণ; উদাহরণ: 100।
`currency`	বর্তমান মুদ্রা কোড: `BDT`।
`customer_name`	গ্রাহকের নাম; ঐচ্ছিক।
`customer_mobile`	গ্রাহকের মোবাইল নম্বর; ঐচ্ছিক।
`customer_email`	গ্রাহকের ইমেইল; ঐচ্ছিক।
`description`	অর্ডার বা পেমেন্টের সংক্ষিপ্ত বিবরণ; ঐচ্ছিক।

অনুরোধ

curl -X POST "https://smartservices-icps-gov.com/api/v1/gateway/payments" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nict_at_xxxxxxxxx" \
  -d '{
    "tran_id": "ORDER-1001",
    "amount": 100,
    "currency": "BDT",
    "customer_name": "Customer Name",
    "customer_mobile": "017XXXXXXXX",
    "customer_email": "customer@example.com",
    "description": "Order payment"
  }'

সফল উত্তর

{
  "success": true,
  "message": "পেমেন্ট সেশন সফলভাবে তৈরি হয়েছে।",
  "data": {
    "session_id": "PS260918XXXXXXXX",
    "tran_id": "ORDER-1001",
    "amount": 100,
    "currency": "BDT",
    "status": "initiated",
    "payment_url": "https://smartservices-icps-gov.com/checkout/PS260918XXXXXXXX",
    "expires_at": "2026-09-18T06:00:00+06:00"
  }
}

পেমেন্টের অবস্থা যাচাই

POSThttps://smartservices-icps-gov.com/api/v1/gateway/payments/status

tran_id, session_id অথবা transaction_uid-এর যেকোনো একটি দিয়ে সার্ভার থেকে লেনদেন যাচাই করুন। সফল পেমেন্ট নিশ্চিত করার জন্য এই উত্তর ব্যবহার করুন।

initiated / pendingপেমেন্ট এখনও সম্পন্ন হয়নি।

successপেমেন্ট সফল।

failed / cancelledপেমেন্ট সম্পন্ন হয়নি।

JSON

{
  "tran_id": "ORDER-1001"
}

সফল, ব্যর্থ ও বাতিল URL

গ্রাহকের ব্রাউজার পেমেন্ট শেষ হলে সংরক্ষিত URL-এ পাঠানো হয়। Query string-এ tran_id, status এবং transaction_uid পাওয়া যায়।

সফল URLstatus=success পাওয়া যায়। সার্ভার থেকে পেমেন্ট স্ট্যাটাস API দিয়ে যাচাই করে তারপর অর্ডার সম্পন্ন করুন।

ব্যর্থ URLstatus=failed পাওয়া যায়।

বাতিল URLstatus=cancelled পাওয়া যায়।

PHP — রিটার্ন URL

<?php
$tranId = $_GET['tran_id'] ?? '';
$status = $_GET['status'] ?? '';
$transactionUid = $_GET['transaction_uid'] ?? '';

if ($status === 'success') {
    // আপনার সার্ভার থেকে status API দিয়ে যাচাই করুন।
} elseif ($status === 'failed') {
    // অর্ডারকে ব্যর্থ হিসেবে দেখান।
} elseif ($status === 'cancelled') {
    // গ্রাহক পেমেন্ট বাতিল করেছেন।
}

Webhook গ্রহণ

পেমেন্ট সফল, ব্যর্থ বা বাতিল হলে সংরক্ষিত Webhook URL-এ JSON POST পাঠানো হয়। Webhook গ্রহণ করে দ্রুত HTTP 200 উত্তর দিন এবং tran_id বা transaction_uid দিয়ে স্ট্যাটাস API থেকে লেনদেন যাচাই করুন।

ফিল্ড	বিবরণ
`event`	`payment.success`, `payment.failed` অথবা `payment.cancelled`।
`transaction_uid`	NICT লেনদেনের অনন্য পরিচয়।
`tran_id`	আপনার পাঠানো লেনদেন নম্বর।
`status`	লেনদেনের বর্তমান অবস্থা।
`amount`	গ্রাহকের পেমেন্টের পরিমাণ।
`merchant_amount`	গেটওয়ে চার্জের পর মার্চেন্টের প্রাপ্য পরিমাণ।
`gateway_trx_id`	পেমেন্ট মাধ্যমের লেনদেন নম্বর।

Webhook JSON

{
  "event": "payment.success",
  "transaction_uid": "TX260918XXXXXXXX",
  "tran_id": "ORDER-1001",
  "session_id": "PS260918XXXXXXXX",
  "status": "success",
  "amount": 100,
  "merchant_amount": 97.5,
  "currency": "BDT",
  "payment_method": "bkash",
  "gateway_trx_id": "A1B2C3D4",
  "paid_at": "2026-09-18T05:45:00+06:00",
  "verify_url": "https://smartservices-icps-gov.com/api/v1/gateway/payments/status"
}

PHP — Webhook

<?php
$payload = json_decode(file_get_contents('php://input'), true);

if (!is_array($payload) || empty($payload['tran_id'])) {
    http_response_code(400);
    exit('INVALID');
}

// payload সংরক্ষণ করুন এবং status API দিয়ে যাচাই করুন।
http_response_code(200);
echo 'OK';

সার্ভার থেকে যাচাই

রিটার্ন URL বা Webhook পাওয়ার পর পেমেন্টের চূড়ান্ত অবস্থা জানতে স্ট্যাটাস API ব্যবহার করুন। ব্রাউজারের query string-কে একমাত্র প্রমাণ হিসেবে ব্যবহার করবেন না।

cURL

curl -X POST "https://smartservices-icps-gov.com/api/v1/gateway/payments/status" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nict_at_xxxxxxxxx" \
  -d '{"tran_id":"ORDER-1001"}'

URL সংরক্ষণ না থাকলে

চারটি URL-এর যেকোনো একটি অনুপস্থিত থাকলে পেমেন্ট তৈরির অনুরোধ 422 HTTP অবস্থায় বন্ধ হবে। মার্চেন্ট প্যানেলে URL সম্পূর্ণ করে আবার অনুরোধ পাঠান।

ত্রুটি উত্তর

{
  "success": false,
  "message": "পেমেন্ট গেটওয়ে ব্যবহারের আগে মার্চেন্ট প্যানেল থেকে সফল, ব্যর্থ, বাতিল এবং Webhook URL—চারটিই সংরক্ষণ করুন।",
  "error_code": "GATEWAY_CALLBACK_URLS_REQUIRED"
}