Integration Guide & Specifications

This document outlines the general standards, HTTP headers, RSA signature algorithms, and key generation instructions for merchants integrating with the Bangladesh Payment Gateway.

---

1. General Request Standards

Interaction Type	HTTP Method	Content-Type	Payload Format
API Requests (Order creation, queries, balance, etc.)	POST	application/json; charset=utf-8	JSON
Webhook Callbacks (Pushed from platform to merchant)	POST	application/json; charset=utf-8	JSON

---

2. Common HTTP Headers

All HTTP POST requests sent to the platform, as well as asynchronous webhook notifications sent by the platform, must include the following headers:

Header Key	Required	Type	Description
merchantNo	Yes	String	Merchant ID issued by the platform
sign	Yes	String	Base64-encoded RSA digital signature of the request body

---

3. RSA Signature & Verification Algorithm

1. Signature Process (Merchant $\to$ Platform)

1. Construct the request parameter map/object according to the specific API specification;
2. Serialize the parameters into a standard JSON string (used as the HTTP Request Body);
3. Sign the JSON string using the Merchant's Private Key with the SHA256withRSA algorithm;
4. Convert the signature byte array into a Base64-encoded string and place it in the HTTP Header sign;
5. Put the merchant ID in the HTTP Header merchantNo and execute the HTTP POST request.

2. Verification Process (Platform $\to$ Merchant Callback)

1. Platform Verifies Merchant Requests: The platform uses the merchant's configured public key to verify sign against the raw request body;
2. Merchant Verifies Platform Callbacks: When receiving asynchronous notifications from the platform, the merchant must verify the sign header using the Platform Public Key (Note: Verification should ignore case differences).

---

4. Platform Public Key

Sandbox / Test Channel Public Key

NOTE

Below is the platform public key for the test environment, used to verify signatures of platform callbacks (Production public key can be viewed in Merchant Portal -> Account Information):

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==

---

5. Java Code Examples

1. Signature & Verification Utility (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);

    /**
     * Verifies the signature of the payload
     * @param param The JSON payload string
     * @param sign Base64 encoded signature string from HTTP header
     * @param publicKey Base64 encoded public key
     * @return true if valid, false otherwise
     */
    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("Signature verification error: ", e);
        }
        return false;
    }

    /**
     * Generates a digital signature for the payload
     * @param param The JSON payload string to sign
     * @param privateKey Base64 encoded private key
     * @return Base64 encoded signature string
     */
    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("Signature generation error: ", e);
        }
        return null;
    }
}

2. Request Demo

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"); // Channel type: BKASH or 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 Status: " + response.getStatus());
        System.out.println("Response Body: " + response.getBody());
    }
}

3. RSA KeyPair Generation Demo

Merchants must generate an RSA-4096 (or RSA-2048) key pair before integration. Provide the generated public key to the platform operations team:

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("--- Merchant Public Key (Provide to Platform) ---");
        System.out.println(publicKeyBase64);

        PrivateKey privateKey = keyPair.getPrivate();
        String privateKeyBase64 = Base64.getEncoder().encodeToString(privateKey.getEncoded());
        System.out.println("--- Merchant Private Key (Keep strictly confidential) ---");
        System.out.println(privateKeyBase64);
    }
}

---

VI. Merchant RSA Key Generation Guide

6.1 Online Key Generation Tools

Tool Links:

• a. RSA KeyPair Generator (Select 1024-bit, 2048-bit, or 4096-bit / PKCS#8 format): https://www.bejson.com/enc/rsa/#18
• b. Line Break Removal Tool (Remove line breaks before uploading): http://www.wuqianling.top/software/notepad/compress.html

Generation & Configuration Steps:

1. Generate KeyPair: Use the key generator to generate a key pair. The length must be 1024bit, 2048bit, or 4096bit, and the format must be PKCS#8.
2. Remove Line Breaks & Upload Public Key: Copy the public key from the generated key pair, remove all newlines/line breaks, and upload it to the Merchant Portal. Do not include -----BEGIN *** KEY----- and -----END *** KEY-----.
3. Safeguard Private Key: After uploading the public key, keep the private key strictly secure and confidential.
4. Technical Support: If you encounter issues with encryption or signing during integration, send your request parameters to the support group and tag (@) customer service or technical support.
5. Callback Signature Verification: For platform webhook callbacks, use the Platform Public Key for signature verification. Never use your merchant public key.

WARNING

Webhook callbacks are sent by the platform. You must verify them using the Platform Public Key, not your own merchant public key.