ইন্টিগ্রেশন নির্দেশিকা ও প্রযুক্তিগত বিবরণ (Integration Guide)

এই নথিতে বাংলাদেশ পেমেন্ট গেটওয়েতে মার্চেন্ট ইন্টিগ্রেশনের সাধারণ নিয়মাবলী, HTTP হেডার স্ট্যান্ডার্ড, RSA ডিজিটাল স্বাক্ষর অ্যালগরিদম এবং কী (Key) তৈরির নিয়মাবলী বর্ণনা করা হয়েছে।

---

১. সাধারণ রিকোয়েস্ট স্পেসিফিকেশন

যোগাযোগের ধরন	HTTP মেথড	Content-Type হেডার	পেলোড ফরম্যাট
API রিকোয়েস্ট (অর্ডার তৈরি, অনুসন্ধান, ব্যালেন্স ইত্যাদি)	POST	application/json; charset=utf-8	JSON
কলব্যাক নোটিফিকেশন (প্ল্যাটফর্ম থেকে মার্চেন্ট সিস্টেমে পুশ)	POST	application/json; charset=utf-8	JSON

---

২. সাধারণ রিকোয়েস্ট হেডার (HTTP Headers)

প্ল্যাটফর্মে পাঠানো সমস্ত API রিকোয়েস্ট এবং প্ল্যাটফর্ম কর্তৃক প্রেরিত কলব্যাক নোটিফিকেশনে নিম্নলিখিত হেডার থাকা বাধ্যতামূলক:

হেডার প্যারামিটার	বাধ্যতামূলক	ধরন (Type)	বিবরণ
merchantNo	হ্যাঁ (Yes)	String	প্ল্যাটফর্ম কর্তৃক প্রদত্ত মার্চেন্ট নম্বর
sign	হ্যাঁ (Yes)	String	রিকোয়েস্ট বডির Base64 এনকোডেড RSA ডিজিটাল স্বাক্ষর

---

৩. RSA ডিজিটাল স্বাক্ষর এবং যাচাইকরণ অ্যালগরিদম

১. স্বাক্ষর তৈরি প্রক্রিয়া (মার্চেন্ট $\to$ প্ল্যাটফর্ম)

১. নির্দিষ্ট এপিআই স্পেসিফিকেশন অনুযায়ী রিকোয়েস্ট প্যারামিটার তৈরি করুন;
২. প্যারামিটারগুলোকে একটি প্রমিত JSON স্ট্রিং-এ রূপান্তর করুন (রিকোয়েস্ট বডি হিসেবে ব্যবহৃত হবে);
৩. মার্চেন্টের নিজস্ব প্রাইভেট কি (Private Key) ব্যবহার করে SHA256withRSA অ্যালগরিদমের মাধ্যমে উক্ত JSON স্ট্রিং স্বাক্ষর করুন;
৪. স্বাক্ষরিত বাইট অ্যারে-টিকে Base64-এ রূপান্তর করে HTTP হেডার sign-এ যুক্ত করুন;
৫. মার্চেন্ট নম্বরটি HTTP হেডার merchantNo-তে যুক্ত করে HTTP POST রিকোয়েস্ট প্রেরণ করুন।

২. স্বাক্ষর যাচাইকরণ প্রক্রিয়া (প্ল্যাটফর্ম $\to$ মার্চেন্ট কলব্যাক)

১. মার্চেন্টের রিকোয়েস্ট প্ল্যাটফর্ম কর্তৃক যাচাই: মার্চেন্টের নিবন্ধিত পাবলিক কি ব্যবহার করে প্ল্যাটফর্ম রিকোয়েস্ট বডি ও sign যাচাই করে;
২. প্ল্যাটফর্মের কলব্যাক মার্চেন্ট কর্তৃক যাচাই: প্ল্যাটফর্ম থেকে পাঠানো অ্যাসিনক্রোনাস কলব্যাক গ্রহণের পর মার্চেন্ট সিস্টেমকে অবশ্যই প্ল্যাটফর্মের পাবলিক কি (Public Key) ব্যবহার করে sign যাচাই করতে হবে (দ্রষ্টব্য: যাচাইয়ের সময় অক্ষরের বড়/ছোট হাতের পার্থক্য বা কেস সংবেদনশীলতা উপেক্ষা করুন)।

---

৪. প্ল্যাটফর্মের পাবলিক কি (Public Key)

টেস্ট চ্যানেল পাবলিক কি (Sandbox)

NOTE

নিচে টেস্ট এনভায়রনমেন্টের প্ল্যাটফর্ম পাবলিক কি দেওয়া হলো, যা প্ল্যাটফর্মের কলব্যাক সিগনেচার যাচাই করতে ব্যবহৃত হয় (প্রোডাকশন পাবলিক কি মার্চেন্ট পোর্টাল -> অ্যাকাউন্ট ইনফরমেশনে দেখতে পাবেন):

MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAx370DGx1EXhyRVF242HkEtGAYuGbG51bE8Ne/lMgRJXnCZLvL4jYsb+3X8vRxLhitzp/iU6Dtdo0f5dMWW8i2ofnZPkg0bD2jeXXsK5KvGYh89Y0SrNROspQcMR+e2R7XdXVfjwiPcTwnpAviYPgFkgIBB0ZpssO4BVMeYeh51dc496emQadB4KXaN7KJGld1nimzYVUigA6SQfMV5jHiD4BgVRSWof3f6I2H4hdFpLniQ+rY/zAC3mwMdKP6/UIFp83DIzRSszjsLVdZ/BA5re9Ifur9Rlps/CY0+N28om/e9U5wXxuGuGWtiJ/Y4lMm8DzxzNTVq+SBShWFCCdnHxfn4Y3TwgXYg1s4uIue3XMcSfLa9nwq31UvMq7+YH0JeVduWsdtvyzJ+ZD8oQ30CwPNkPFpT3lCH78Quq269PRFvxtWOFS2t4gS4yEQgwIwN9jzT0WLhLK9HFs9/4+6kQEpHe0BrFoGKyAhtUvejj8elLJnb+3vX+zkQVFbKwWMyJsGKH1dcdpR8k6Q4XBYe9zDo+jJw34LFo5h+oX5ImwDoLc5VxvbwT7lDpBcAXygP96rTIvCh9HGQkAZSgLyI5UrjAmv1nV6PpWc8DooMxyMzFpjIzkKYd+juC6GYIbh1Vnb45lgJns42irOzYoyVGL+dxZ27m0/0lmxSW5t7UCAwEAAQ==

---

৫. জাভা কোড উদাহরণ (Java Code Examples)

১. সাইন ইউটিলিটি ক্লাস (SignUtil.java)

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.security.KeyFactory;
import java.security.Signature;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

public class SignUtil {

    private static final Logger LOGGER = LoggerFactory.getLogger(SignUtil.class);

    /**
     * ডিজিটাল স্বাক্ষর যাচাইকরণ মেথড
     * @param param JSON বডি স্ট্রিং
     * @param sign HTTP হেডারের Base64 সাইন
     * @param publicKey Base64 পাবলিক কি
     * @return স্বাক্ষর সঠিক হলে true, অন্যথায় false
     */
    public static boolean checkSign(String param, String sign, String publicKey) {
        try {
            Signature signature = Signature.getInstance("SHA256withRSA");
            KeyFactory keyFactory = KeyFactory.getInstance("RSA");
            signature.initVerify(keyFactory.generatePublic(new X509EncodedKeySpec(Base64.getDecoder().decode(publicKey))));
            signature.update(param.getBytes());
            return signature.verify(Base64.getDecoder().decode(sign));
        } catch (Exception e) {
            LOGGER.error("Sign যাচাইকরণে ত্রুটি: ", e);
        }
        return false;
    }

    /**
     * ডিজিটাল স্বাক্ষর তৈরির মেথড
     * @param param স্বাক্ষরের জন্য JSON বডি
     * @param privateKey Base64 প্রাইভেট কি
     * @return Base64 সাইন স্ট্রিং
     */
    public static String sign(String param, String privateKey) {
        try {
            Signature signature = Signature.getInstance("SHA256withRSA");
            KeyFactory keyFactory = KeyFactory.getInstance("RSA");
            signature.initSign(keyFactory.generatePrivate(new PKCS8EncodedKeySpec(Base64.getDecoder().decode(privateKey))));
            signature.update(param.getBytes());
            byte[] bytes = signature.sign();
            return Base64.getEncoder().encodeToString(bytes);
        } catch (Exception e) {
            LOGGER.error("Sign তৈরিতে ত্রুটি: ", e);
        }
        return null;
    }
}

২. রিকোয়েস্ট পাঠানোর উদাহরণ

import com.google.gson.Gson;
import kong.unirest.HttpResponse;
import kong.unirest.Unirest;
import java.util.HashMap;
import java.util.Map;

public class RequestDemo {
    public static void main(String[] args) {
        String url = "https://api.example.com/payin/create";
        String merchantNo = "M1639466186292";
        String privateKey = "YOUR_PRIVATE_KEY_BASE64";

        Map<String, Object> map = new HashMap<>();
        map.put("timestamp", System.currentTimeMillis());
        map.put("merchantOrderNo", "ORDER_" + System.currentTimeMillis());
        map.put("amount", "200.00");
        map.put("payType", "BKASH"); // চ্যানেল মাধ্যম: BKASH বা NAGAD
        map.put("notifyUrl", "https://yourdomain.com/payin/notify");

        Gson gson = new Gson();
        String body = gson.toJson(map);
        String sign = SignUtil.sign(body, privateKey);

        HttpResponse<String> response = Unirest.post(url)
                .header("Content-Type", "application/json; charset=utf-8")
                .header("merchantNo", merchantNo)
                .header("sign", sign)
                .body(body)
                .asString();

        System.out.println("HTTP স্ট্যাটাস: " + response.getStatus());
        System.out.println("রেসপন্স বডি: " + response.getBody());
    }
}

৩. RSA কী-পেয়ার (KeyPair) তৈরির উদাহরণ

ইন্টিগ্রেশন শুরু করার পূর্বে মার্চেন্টকে অবশ্যই একটি RSA-4096 (বা RSA-2048) কী জোড়া তৈরি করতে হবে এবং পাবলিক কি-টি প্ল্যাটফর্মে জমা দিতে হবে:

import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.NoSuchAlgorithmException;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.util.Base64;

public class KeyPairGenDemo {
    public static void main(String[] args) throws NoSuchAlgorithmException {
        KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
        keyPairGenerator.initialize(4096);
        KeyPair keyPair = keyPairGenerator.genKeyPair();

        PublicKey publicKey = keyPair.getPublic();
        String publicKeyBase64 = Base64.getEncoder().encodeToString(publicKey.getEncoded());
        System.out.println("--- মার্চেন্ট পাবলিক কি (প্ল্যাটফর্মে জমা দিন) ---");
        System.out.println(publicKeyBase64);

        PrivateKey privateKey = keyPair.getPrivate();
        String privateKeyBase64 = Base64.getEncoder().encodeToString(privateKey.getEncoded());
        System.out.println("--- মার্চেন্ট প্রাইভেট কি (গোপনে নিরাপদে রাখুন) ---");
        System.out.println(privateKeyBase64);
    }
}

---

৬. মার্চেন্ট RSA কী তৈরির নির্দেশিকা

৬.১ অনলাইন কী তৈরির টুল

প্রয়োজনীয় টুলস লিংক:

• a. কী-পেয়ার তৈরির টুল (১০২৪, ২০৪৮ অথবা ৪০৯৬ বিট এবং ফরম্যাট PKCS#8 নির্বাচন করুন): https://www.bejson.com/enc/rsa/#18
• b. লাইন ব্রেক সরানোর টুল (আপলোড করার আগে লাইন ব্রেক বা নতুন লাইন মুছুন): http://www.wuqianling.top/software/notepad/compress.html

নির্দেশনা ও সতর্কতা:

১. কী-পেয়ার তৈরি: অনলাইন টুল ব্যবহার করে কী-পেয়ার তৈরি করুন। সাইজ অবশ্যই 1024bit, 2048bit অথবা 4096bit হতে হবে এবং ফরম্যাট অবশ্যই PKCS#8 হতে হবে। ২. পাবলিক কি আপলোড: তৈরিকৃত পাবলিক কি-টি থেকে সমস্ত লাইন ব্রেক মুছে মার্চেন্ট পোর্টালে আপলোড করুন। মনে রাখবেন, -----BEGIN *** KEY----- এবং -----END *** KEY----- বাদ দিয়ে শুধুমাত্র মূল কি টেক্সট কপি করতে হবে। ৩. প্রাইভেট কি সংরক্ষণ: পাবলিক কি আপলোড করার পর প্রাইভেট কি-টি অত্যন্ত নিরাপদে সংরক্ষণ করুন। ৪. টেকনিক্যাল সাপোর্ট: ইন্টিগ্রেশন বা এনক্রিপশন নিয়ে কোনো সমস্যা হলে প্যারামিটারসমূহ সাপোর্ট গ্রুপে পাঠিয়ে কাস্টমার সার্ভিস বা টেকনিক্যাল টিমকে মেনশন (@) করুন। ৫. কলব্যাক ভেরিফিকেশন: প্ল্যাটফর্ম থেকে পাঠানো কলব্যাক নোটিফিকেশন ভেরিফাই করার জন্য অবশ্যই প্ল্যাটফর্ম পাবলিক কি (Platform Public Key) ব্যবহার করুন। মার্চেন্টের নিজস্ব পাবলিক কি দিয়ে কলব্যাক ভেরিফাই করবেন না।

WARNING

প্ল্যাটফর্ম কলব্যাক ভেরিফাই করতে সর্বদা প্ল্যাটফর্মের পাবলিক কি ব্যবহার করতে হবে।