HaiPay

English

简体中文

English

简体中文

Appearance

Config & Signature

About 2959 wordsAbout 10 min

1. Obtain Merchant Self-Service Platform Account

After the partnership is confirmed, HaiPay will create an administrator account for the merchant to log into the Merchant Management Self-Service Platform, based on the "Administrator Account Information" filled out in the "Merchant Access Application Form." Please pay attention to the activation email sent by HaiPay. The merchant can activate the administrator account according to the instructions in the email. The first login will require a password change, so please ensure the password is secure to prevent leakage.

2. Obtain appId and Secret Key

The merchant's appId required for integration testing can be obtained from the Merchant Management Platform. The signature uses the SHA256WithRSA signing algorithm, and the merchant needs to generate the public and private key pair themselves. The public key must be uploaded to the Merchant Management Platform, and HaiPay's public key should also be downloaded. Please securely store the key information. If the key is leaked, it should be updated immediately.

Configuration entry: "Business Management" - "Payment Product Configuration"

Warning

The merchant's appId and secret key are paired, distinguished by currency, and differentiated between the test environment and the production environment.

3. Public Key and Private Key Configuration

3.1 Role of Public and Private Keys

3.2 Generating Public and Private Keys

The private key should be securely stored, and the public key should be added to the HaiPay backend. Remove the -----BEGIN XXX KEY----- and -----END XXX KEY----- parts, along with any newlines and spaces.

Method 1: Use OpenSSL to Generate Keys

Refer to online examples; OpenSSL needs to be installed, and the key length should be 2048 bits.

Method 2: Generate Keys Online

You can generate key pairs using the HaiPay Developer Tools, which are implemented purely in JavaScript and will not interact with the HaiPay server, ensuring that merchant key information is not leaked. Generates addresses, alternatively, other online tools can be used to generate the key pair.

Method 3: Generate Keys via Code

Merchants can generate public and private keys using the following SDK. The merchant's private key should be securely stored and used for signing requests to HaiPay. The merchant’s public key should be uploaded to the platform for HaiPay to verify the merchant’s signature to prevent tampering during transmission. Additionally, the HaiPay public key should be obtained from the platform and integrated into the merchant’s system for verifying the HaiPay-signed messages.

Generate key
java
    /**
     * Generates a 2048-bit RSA key pair and converts the public and private keys to PEM format.
     *
     * @return A Map containing the public and private keys, with keys "publicKey" and "privateKey".
     */
    public static Map<String, String> generateRSAKeyPair() {
        try {
            // Create KeyPairGenerator object and specify RSA algorithm
            KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");

            // Initialize the key length to 2048 bits
            keyPairGenerator.initialize(2048);

            // Generate the key pair
            KeyPair keyPair = keyPairGenerator.generateKeyPair();

            // Retrieve the public and private keys
            PublicKey publicKey = keyPair.getPublic();
            PrivateKey privateKey = keyPair.getPrivate();

            // Convert the public and private keys to PEM format
            String publicKeyPem = convertPublicKeyToPEM(publicKey);
            String privateKeyPem = convertPrivateKeyToPEM(privateKey);

            // Store the public and private keys in a Map
            Map<String, String> keyPairMap = new HashMap<>();
            keyPairMap.put("publicKey", publicKeyPem);
            keyPairMap.put("privateKey", privateKeyPem);
            return keyPairMap;

        } catch (NoSuchAlgorithmException e) {
            throw new RuntimeException("Failed to generate RSA key pair", e);
        }
    }

    /**
     * Converts the public key to PEM format.
     *
     * @param publicKey The public key object.
     * @return The public key as a PEM formatted string.
     */
    private static String convertPublicKeyToPEM(PublicKey publicKey) {
        String encodedPublicKey = Base64.getMimeEncoder(64, "\n".getBytes())
                .encodeToString(publicKey.getEncoded());
        return "-----BEGIN PUBLIC KEY-----\n"
                + encodedPublicKey
                + "\n-----END PUBLIC KEY-----";
    }

    /**
     * Converts the private key to PEM format.
     *
     * @param privateKey The private key object.
     * @return The private key as a PEM formatted string.
     */
    private static String convertPrivateKeyToPEM(PrivateKey privateKey) {
        String encodedPrivateKey = Base64.getMimeEncoder(64, "\n".getBytes())
                .encodeToString(privateKey.getEncoded());
        return "-----BEGIN PRIVATE KEY-----\n"
                + encodedPrivateKey
                + "\n-----END PRIVATE KEY-----";
    }

4. Signature

TypeDescription
AlgorithmRSA
Signature AlgorithmSHA256WithRSA
Key Length2048

Unified signature generation rule:

RSA-based signature verification method

Sort all non-empty parameters by their ASCII keys, then concatenate the key (excluding sign) and value, using the format k1=v1&k2=v2&.... At the end, append &key=merchantSecretKey (the encryption key, obtained from the backend).

Use the RSA algorithm to calculate the string and generate the signature.

The API may add response fields. When verifying the signature, the added fields must be supported.

Signature Tool
java
import lombok.extern.slf4j.Slf4j;
import org.apache.tomcat.util.http.fileupload.IOUtils;

import javax.crypto.Cipher;
import java.io.ByteArrayOutputStream;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
import java.security.Key;
import java.security.KeyFactory;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.NoSuchAlgorithmException;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.security.Signature;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;

/**
 * @ClassName SHA256WithRSAUtils
 * @Description (SHA256WithRSA Signature Utility Class)
 * @Author Finlay
 * @Date 2021-02-01
 * @Version 1.0.0
 */
@Slf4j
public class SHA256WithRSAUtils {

    public static final Charset CHARSET = StandardCharsets.UTF_8;
    /**
     * Key Algorithm
     */
    public static final String ALGORITHM_RSA = "RSA";
    /**
     * RSA Signature Algorithm
     */
    public static final String ALGORITHM_RSA_SIGN = "SHA256WithRSA";
    public static final int ALGORITHM_RSA_PRIVATE_KEY_LENGTH = 2048;

    private SHA256WithRSAUtils() {
    }

    /**
     * RSA Algorithm Public Key Encryption
     *
     * @param data The plain text string to be encrypted
     * @param key  RSA public key string
     * @return The encrypted cipher text string, encoded in Base64
     */
    public static String buildRSAEncryptByPublicKey(String data, String key) {
        try {
            // Get the public key object through X509-encoded Key instruction
            X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(Base64.getDecoder().decode(key));
            KeyFactory keyFactory = KeyFactory.getInstance(ALGORITHM_RSA);
            Key publicKey = keyFactory.generatePublic(x509KeySpec);
            Cipher cipher = Cipher.getInstance(keyFactory.getAlgorithm());
            cipher.init(Cipher.ENCRYPT_MODE, publicKey);
            return Base64.getEncoder().encodeToString(rsaSplitCodec(cipher, Cipher.ENCRYPT_MODE, data.getBytes(CHARSET)));
        } catch (Exception e) {
            throw new RuntimeException("An error occurred while encrypting the string [" + data + "]", e);
        }
    }

    /**
     * RSA Algorithm Public Key Decryption
     *
     * @param data The Base64-encoded cipher text string to be decrypted
     * @param key  RSA public key string
     * @return The decrypted plain text string
     */
    public static String buildRSADecryptByPublicKey(String data, String key) {
        try {
            // Get the public key object through X509-encoded Key instruction
            X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(Base64.getDecoder().decode(key));
            KeyFactory keyFactory = KeyFactory.getInstance(ALGORITHM_RSA);
            Key publicKey = keyFactory.generatePublic(x509KeySpec);
            Cipher cipher = Cipher.getInstance(keyFactory.getAlgorithm());
            cipher.init(Cipher.DECRYPT_MODE, publicKey);
            return new String(rsaSplitCodec(cipher, Cipher.DECRYPT_MODE, Base64.getDecoder().decode(data)), CHARSET);
        } catch (Exception e) {
            throw new RuntimeException("An error occurred while decrypting the string [" + data + "]", e);
        }
    }

    /**
     * RSA Algorithm Private Key Encryption
     *
     * @param data The plain text string to be encrypted
     * @param key  RSA private key string
     * @return The encrypted cipher text string, encoded in Base64
     */
    public static String buildRSAEncryptByPrivateKey(String data, String key) {
        try {
            // Get the private key object through PKCS#8-encoded Key instruction
            PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(Base64.getDecoder().decode(key));
            KeyFactory keyFactory = KeyFactory.getInstance(ALGORITHM_RSA);
            Key privateKey = keyFactory.generatePrivate(pkcs8KeySpec);
            Cipher cipher = Cipher.getInstance(keyFactory.getAlgorithm());
            cipher.init(Cipher.ENCRYPT_MODE, privateKey);
            return Base64.getEncoder().encodeToString(rsaSplitCodec(cipher, Cipher.ENCRYPT_MODE, data.getBytes(CHARSET)));
        } catch (Exception e) {
            throw new RuntimeException("An error occurred while encrypting the string [" + data + "]", e);
        }
    }

    /**
     * RSA Algorithm Private Key Decryption
     *
     * @param data The Base64-encoded cipher text string to be decrypted
     * @param key  RSA private key string
     * @return The decrypted plain text string
     */
    public static String buildRSADecryptByPrivateKey(String data, String key) {
        try {
            // Get the private key object through PKCS#8-encoded Key instruction
            PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(Base64.getDecoder().decode(key));
            KeyFactory keyFactory = KeyFactory.getInstance(ALGORITHM_RSA);
            Key privateKey = keyFactory.generatePrivate(pkcs8KeySpec);
            Cipher cipher = Cipher.getInstance(keyFactory.getAlgorithm());
            cipher.init(Cipher.DECRYPT_MODE, privateKey);
            return new String(rsaSplitCodec(cipher, Cipher.DECRYPT_MODE, Base64.getDecoder().decode(data)), CHARSET);
        } catch (Exception e) {
            throw new RuntimeException("An error occurred while decrypting the string [" + data + "]", e);
        }
    }

    /**
     * RSA Algorithm Private Key Digital Signature Generation
     *
     * @param data The plain text string to be signed
     * @param key  RSA private key string
     * @return The Base64-encoded signed string using RSA private key
     */
    public static String buildRSASignByPrivateKey(String data, String key) {
        try {
            // Get the private key object through PKCS#8-encoded Key instruction
            PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(Base64.getDecoder().decode(key));
            KeyFactory keyFactory = KeyFactory.getInstance(ALGORITHM_RSA);
            PrivateKey privateKey = keyFactory.generatePrivate(pkcs8KeySpec);
            Signature signature = Signature.getInstance(ALGORITHM_RSA_SIGN);
            signature.initSign(privateKey);
            signature.update(data.getBytes(CHARSET));
            return Base64.getEncoder().encodeToString(signature.sign());
        } catch (Exception e) {
            throw new RuntimeException("An error occurred while signing the string [" + data + "]", e);
        }
    }

    /**
     * RSA Algorithm Public Key Signature Verification
     *
     * @param data  The plain text string that was signed
     * @param key   RSA public key string
     * @param sign  The Base64-encoded signature string obtained from RSA signing
     * @return true--signature verified, false--signature verification failed
     */
    public static boolean buildRSAverifyByPublicKey(String data, String key, String sign) {
        try {
            // Get the public key object through X509-encoded Key instruction
            X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(Base64.getDecoder().decode(key));
            KeyFactory keyFactory = KeyFactory.getInstance(ALGORITHM_RSA);
            PublicKey publicKey = keyFactory.generatePublic(x509KeySpec);
            Signature signature = Signature.getInstance(ALGORITHM_RSA_SIGN);
            signature.initVerify(publicKey);
            signature.update(data.getBytes(CHARSET));
            return signature.verify(Base64.getDecoder().decode(sign));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    /**
     * RSA Algorithm for Chunked Encryption/Decryption of Data
     *
     * @param cipher The javax.crypto.Cipher object initialized with the encryption/decryption mode
     * @param opmode The operation mode (Cipher.ENCRYPT_MODE / Cipher.DECRYPT_MODE)
     * @return The byte array of encrypted or decrypted data
     */
    private static byte[] rsaSplitCodec(Cipher cipher, int opmode, byte[] datas) {
        int maxBlock = 0;
        if (opmode == Cipher.DECRYPT_MODE) {
            maxBlock = ALGORITHM_RSA_PRIVATE_KEY_LENGTH / 8;
        } else {
            maxBlock = ALGORITHM_RSA_PRIVATE_KEY_LENGTH / 8 - 11;
        }
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        int offSet = 0;
        byte[] buff;
        int i = 0;
        try {
            while (datas.length > offSet) {
                if (datas.length - offSet > maxBlock) {
                    buff = cipher.doFinal(datas, offSet, maxBlock);
                } else {
                    buff = cipher.doFinal(datas, offSet, datas.length - offSet);
                }
                out.write(buff, 0, buff.length);
                i++;
                offSet = i * maxBlock;
            }
        } catch (Exception e) {
            throw new RuntimeException("An error occurred while encrypting/decrypting data with the threshold [" + maxBlock + "]", e);
        }
        byte[] resultDatas = out.toByteArray();
        IOUtils.closeQuietly(out);
        return resultDatas;
    }
}
Generate Signature String
java
public static String getSign(Object obj, String secretKey) {
    Map<String, Object> map;
    if (obj instanceof Map) {
        map = (Map<String, Object>) obj;
    } else {
        map = BeanMapTool.beanToMap(obj);
    }
    Set<String> keys = map.keySet();
    List<String> list = new ArrayList<>(keys);
    Collections.sort(list);
    // Construct the format for the signature key-value pair
    StringBuilder sb = new StringBuilder();
    // Construct the format for the signature key-value pair
    for (String key : list) {
        Object val = map.get(key);
        // If the key is not sign_type or sign, and the key is not empty, append it to the signature string.
        if (!("".equals(val) || val == null || List.of("sign_type", "sign").contains(key))) {
            sb.append(key).append("=").append(val).append("&");
        }
    }
    sb.append("key=").append(secretKey);
    return sb.toString();
}



// package com.haipay.admin.utils;
import org.springframework.cglib.beans.BeanMap;
import java.lang.reflect.InvocationTargetException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * Bean and Map Conversion
 */
public class BeanMapTool {
    public static <T> Map<String, Object> beanToMap(T bean) {
        BeanMap beanMap = BeanMap.create(bean);
        Map<String, Object> map = new HashMap<>();
        beanMap.forEach((key, value) -> map.put(String.valueOf(key), value));
        return map;
    }
}
Signature Verification Test Demo
java
public static void main(String[] args) {
        String privateKey = "MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCKqgxszb4ObuoJ5U8Ddz2ytOFFc81fmniRFo+jvNtrOegMUpd9gBPvMEaBzdeJC74Cg/HsAE7f9u24APLi0oLYZCwthhs01xTIhAis8h7IYCSdWrcbn8gpB7apSe4Ud0dS6zkuRcDTVGsLNrzNOMKHfT8S13dtsqDyDBBhSpkBwe9TkeLQB8K5ZjDYJ8uTtsrcey95eNFe22r8qAhv562yUBTG0PjZpQmiJWD0T6URLLzNYEOXEzsVVZgPKBNWSVZvMjLg32eFv/2Mw+x83n44w39FLx6E347A5hVQYWbBLuHDyFUzW/endOmMSj1YJmGDhctgEK+UIA1bNbexYo33AgMBAAECggEAZlZ6NRLjYeOZ9xO17OjkMDAu0gNVX2mx8eKkwENx7QEfsXiDNayBCdanMsWofQydf13B/lt72u9zIooQuDaFOw8zS6XeDnFudU582KcY8OmEHF4HJewW3bFDrk1R2OjvStMvsGbqmQ2EsxIC5bMuXrChDFbZXayn+/vLWwKjShetqPkN2cRHcKWaASqOnWOAnpgHm5VuGu2ttaR5K14pmMq7a0TOaj7lDYyHelWejCfqFFiWfYLefNj3oFVAfiNxwsxj8q42xWwPZ/Xzhn8p0cInja//1AMuNLIadyC4r6VR7cOIKm4F7XwCTCRCSmPbhDu5pOEA//pERFTTNtE7gQKBgQDdzbujAJRqkn0WwPtbKE7ZxR2KFjc4fM1LyPyODz4tbXhtXtZeMcjjsKn8pTpzbgj+Cfmhz9X8sKAqdxe1WJTtkgg5zbvPQ8A+Q0Su19LZMfFCuC0RCp1SX/asl4XeQe6fQZCft3AG7RgA5HjHET0/7Mpwb3C7A/xBwMfn51T0+wKBgQCgCuy9NmpG2bG/MEz1gDojYe08yKOGgTLp6v/UZcn+U6Oit37/sFe0vU7n9NMtkCLdhf2mqF1cNCUv+rzHkvtgG8FaNlsuozOMXuTNCJ6nj/IypMOnU8vV9DL9zUq5cUnny7HKwCTuS8FYZTjI75GfDDwrxIhhzOIkh2leQD+iNQKBgDV1xOgA18ToEeZOFUdfa8HpVLlXqW+gBQtjIhxLaD0iyYfy99A0R6s5hX8zg+cWemxgkx6BLZ5+I9yYX8qB00N/kyP7hmzqc4eORxutQVDATNo78gDNgiW8o4Pt8YIkehNAhk84s3O36bUtXD7+1Lh3pkN7WLx6tW5TvNsUUtHJAoGBAIYOoJ8dpYgTccAkRVKfRhO9Q2tW5SMVtgAayJCxcrGGfdseuVKT8+OBb0b83KedxJaqVf3zqcBCLaQy80543/dxSFS4k0hNjDBYjG7yeXMCMG4bdYgDuQpOsyfFfoI3UyDGjva2XDj/W8UfhKFLiz8ekIhY56SEaikPBEPerW7BAoGBAIW+5xD7BH4Z/w+GNrA5WFWNNH02+32AD/k6W59GQ+ejrFzCa9/SPa/7WEbBjKNWnzYl9pcdA0lP3LGEbKzrm6Zy+6lCHI6Hx/o4PbHaKTQg2jAIJdEUrAOKR44rjIY41a8wtgilfZA4I4zDSvJMPkMYOItIXjFCwHTxLLfw0CJp";
        String publicKey = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAiqoMbM2+Dm7qCeVPA3c9srThRXPNX5p4kRaPo7zbaznoDFKXfYAT7zBGgc3XiQu+AoPx7ABO3/btuADy4tKC2GQsLYYbNNcUyIQIrPIeyGAknVq3G5/IKQe2qUnuFHdHUus5LkXA01RrCza8zTjCh30/Etd3bbKg8gwQYUqZAcHvU5Hi0AfCuWYw2CfLk7bK3HsveXjRXttq/KgIb+etslAUxtD42aUJoiVg9E+lESy8zWBDlxM7FVWYDygTVklWbzIy4N9nhb/9jMPsfN5+OMN/RS8ehN+OwOYVUGFmwS7hw8hVM1v3p3TpjEo9WCZhg4XLYBCvlCANWzW3sWKN9wIDAQAB";
        Map<String, Object> request = new HashMap<>();
        request.put("appId", "1000");
        request.put("orderNo", "1000");
        //Obtain String to Be Signed
        String content = SignUtils.getSign(request, "WFZflvcV75jYP2G6QIpSsMtoX1e4awxO");
        //Execute Signature
        String sign = SHA256WithRSAUtils.buildRSASignByPrivateKey(content, privateKey);
        System.out.println("Signature:" + SHA256WithRSAUtils.buildRSASignByPrivateKey(content, privateKey));
        System.out.println("Verification:" + SHA256WithRSAUtils.buildRSAverifyByPublicKey(content, publicKey, SHA256WithRSAUtils.buildRSASignByPrivateKey(content, privateKey)));
    }

5. Example Message

Request

// Philippines Collection Request
POST https://uat-interface.haipay.asia/php/collect/apply
Content-Type: application/json
{
    "appId": 1054,
    "orderId": "M233323000059",
    "amount": "300",
    "phone": "09230219312",
    "email": "23423@qq.com",
    "name": "test",
    "inBankCode": "PH_QRPH_DYNAMIC",
    "payType": "QR",
    // sign: Signed with merchant privateKey based on the request body
    "sign": "af0gAHkUOyYHu9owQp8NJ4mPEeUW4vuJcjdxqLIzrVw8AvpLSjD1DXupReSG/CyuSkFRyiIvCp5u703AuGGmfgD2gKDH3Ywau41bAbG2jnHJ8mtjiSJ5iWUzanyd4Kr7d1+rETbzUl7/BkW3t0X8UUFdqpxwG8DPUjAwUKfplWDHV7koG51Ozexd80DCsmW6eWdouAZ1uNXGLYmV3ftE3BmfNRtuv1C5bfTJWrTEIOxbF6g2uYOFZTlIgrQgd7/2PsAYwQQXNz8Q8CYl4OxqCv4pXJxaLWPbR5tqZu9og5kn32C9aHW/NlU1y39vzz+4ef81yPAqUV9oHlSMSPrMmw=="
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
    "status": "1",
    "error": "00000000",
    "msg": "",
    "data": {
        "orderId": "M233323000059",
        "orderNo": "6023071013539074",
        "payUrl": "https://a.api-uat.php.com/1L9zQS2",
        "bankCode": "GCASH_STATIC_VA",
        "bankNo": "PC0007I10000035",
        "qrCode": "00020101021228760011ph.ppmi.p2m0111OPDVPHM1XXX0315777148000000017041652948137245442930503001520460165303608540810000.php Of Mandalu62310010ph.allbank05062110000803***88310012ph.ppmi.qrph0111OPDVPHM1XXX63042763",
        // sign: HaiPay signature information, merchant verifies the signature using response JSON body and HaiPay publicKey
        "sign": "YEoA8Y2JzQFGVzwJSqmemm1Kfv/bfyIfCqv2dp7RNzT5B72AQvdD+nt2nR4sL1HWscvmNHyVt5ovAi7MMhy3ziih/sMph+wPx4YjH3W1h5DyBvSlWvaKfKrK5ViomZ0pPYWydwRHnnRnicxToHK9S6qtSy7Q73O0hdz4hJ9p41Th3ycBl2Q9SeqSZYSY1ohcPDhdyRf2y0prb8rHgpBKzxZ5BKX/1bsE9OmsSEHAEYT8OGgko6aNe8XPAhr4G48cpWTftvnGQuzh0O65nuZRI/PF+Axt2zJCVbFHDDSREI9NlAT82ebDqhlVdxQzKE67D1nxgjb3dPmDUYHOBpmwxQ=="  
    }
}

Theme by cotmier

Copyright © 2019-2025 HaiPay | MIT License