Global Specification

This section describes the global communication standards of the RivaaPay API, including request methods, signature algorithms, and signature utility code examples.

---

1. Request Method

Transaction Type	HTTP Method	Content-Type	Note
Order Creation & Query	POST	application/json; charset=utf-8	Request from Merchant to Platform
Async Notification Callback	POST	application/json; charset=utf-8	Notification from Platform to Merchant

---

2. Request Headers

For all API requests, the following parameters must be included in the HTTP Header for identity verification:

Parameter	Required	Type	Description
merchantNo	Yes	string	The merchant number, assigned and provided by the platform.
sign	Yes	string	The RSA-SHA256 signature value (Base64 encoded) of the request body JSON string.

---

3. Signature Algorithm

1. Construct Parameters: Construct the request body object according to the parameters specified in the API documentation.
2. Format JSON: Serialize the request body object into a standard JSON string (ensure field structures remain consistent).
3. Sign & Verify:
   • Merchant Request: The merchant signs the JSON request body using their own RSA Private Key and places the Base64 signature result into the sign header. The platform verifies it using the RSA Public Key provided by the merchant.
   • Platform Notification: When the platform sends callbacks, it signs with the platform's private key. The merchant must verify this signature using the Platform Public Key.

Platform Public Key for Testing

IMPORTANT

Below is the platform public key for the test environment to verify notifications (the production public key can be viewed in the merchant backend - account information):

MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0kr9IpgDckceWl1g8IRAMV6hALHspEb+SzIsrcc2+Q9WSot/c9YbRZzd+yuzkazMv4HAHeW7oLkG1lcxFYxgPM2x0GbhWqy1Yk5iiARS0h3E2mbuDy7neaL9DzZ411Xwq/pcoEAaklJtwwkXwlIcJGVHUFAebX6Yc6BitcfSvjZe7ilyVX0LA2aTxRGoF490gWo3R7TEXK/Lmdh/rC6FldyexdlAoc1DYbCBFZJQXxJReBbvNj+jJi1BsrsrbrKXBHd9M7/vzBwrHGDa09Y4Yw1wVPm+ZRFFs8hC3bVlZWrpOrR9o9S9kSH47YmnHDPve8fK9/ySEHp6JZ0QxJOnd6DQ0uGdAWswWlIZ4Jjg2qJxC6PHmoRYeWjyc9BuekUtDv9Yiyi9SBfGJQJStjC9PksKsMtUCGaoszPMLhMDGCX9mvYKuxK+vHDK3csWu2iRtX9TIulk/ojNsoZkSKV9tnsmiPFKb9vD79k2RiRyKYVlwpLe9Gyq/joN32i6qIyuN7h5iyms+mxya3DiGNNGdrYwaRGK+nwyJtuZJ9LI8GvWjcq5hVDeAgYnUs16N/ujCbWzHpvzDpmZxgJHXxHPk9TAFzrbTUJQ4p6TBpY87NHb2ozJcOFkFzoYEmqMhivM7vn4gqmd/r1z7PNfjNpJK2dv7pjUQ28S9FEZnsnnJecCAwEAAQ==

---

4. Java Signature Tool Example

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);

    /**
     * Verify signature
     *
     * @param param     Original JSON string
     * @param sign      Base64 signature value
     * @param publicKey RSA public key string (Base64)
     * @return Whether verification passed
     */
    public static boolean checkSign(String param, String sign, String publicKey) {
        try {
            Signature signature = Signature.getInstance("SHA256withRSA");
            signature.initVerify(KeyFactory.getInstance("RSA").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;
    }

    /**
     * Generate signature
     *
     * @param param      JSON string to sign
     * @param privateKey RSA private key string (Base64)
     * @return Base64 signature string
     */
    public static String sign(String param, String privateKey) {
        try {
            Signature signature = Signature.getInstance("SHA256withRSA");
            signature.initSign(KeyFactory.getInstance("RSA").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;
    }
}

---

5. Request Sending Example (Java)

Map<String, Object> map = new HashMap<>();
map.put("timestamp", String.valueOf(System.currentTimeMillis()));
map.put("merchantOrderNo", "ORDER_123456789");
// ... Populate other parameters

String body = gson.toJson(map);
String sign = SignUtil.sign(body, merchantPrivateKey);

HttpResponse<String> stringHttpResponse = Unirest.post("https://api.xxx.com/payin/create")
        .header("Content-Type", "application/json; charset=utf-8")
        .header("merchantNo", "M1639466186292")
        .header("sign", sign)
        .body(body)
        .asString();

---

6. Merchant RSA Key Pair Generation (Java)

6.1 Online Generation Tool

a. Public and Private Key Generation Tool Link (Select 1024-bit, 2048-bit, 4096-bit / Format PKCS#8): https://www.bejson.com/enc/rsa/#18

b. Use this link to remove line breaks before uploading: http://www.wuqianling.top/software/notepad/compress.html

1. Use the key generation tool to generate a key pair. The length must be 1024-bit, 2048-bit, or 4096-bit, and the format must be PKCS#8.

2. Copy the public key from the generated key pair after removing line breaks, and upload it to the merchant backend. Do not include -----BEGIN *** KEY----- and -----END *** KEY-----.

3. After the public key is uploaded successfully, please keep your private key safe.

4. If there are any issues with integration or encryption, you can send the request parameters to the group and mention our customer service or technical staff.

5. For callback signatures, please use the platform's public key for decryption and verification. Do not use the merchant's public key (the public key you generated yourself).

6.2 Java Code Generation Example

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 KeyPairGen {
    public static void main(String[] args) throws NoSuchAlgorithmException {
        KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
        keyPairGenerator.initialize(4096);
        KeyPair keyPair = keyPairGenerator.genKeyPair();

        // Public Key
        PublicKey publicKey = keyPair.getPublic();
        String publicKeyBase64 = Base64.getEncoder().encodeToString(publicKey.getEncoded());
        System.out.println("----- Public Key (Provide to Platform) -----");
        System.out.println(publicKeyBase64);

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