Skip to main content
This guide takes you from a blank slate to a verified API response in six steps. You will generate a 2048-bit RSA key pair, exchange public keys with Gcashier Pay, download the demo SDK, build an encrypted request envelope, and confirm that the test environment returns a successful response. Plan for about 30 minutes the first time through.
1

Get your credentials from Gcashier Pay

Before you can call any endpoint, Gcashier Pay needs to onboard your merchant account. Contact the Gcashier Pay team to begin the process. Once your account is provisioned you will receive two things:
  • merchantNo — your unique merchant identifier, included as a top-level POST parameter in every request.
  • Gcashier Pay’s RSA public key — used to encrypt the AES session key you generate for each request.
Keep both values secure. Your merchantNo is not a secret on its own, but Gcashier Pay’s public key must come directly from Gcashier Pay — never from a third-party source.
2

Generate your 2048-bit RSA key pair

You need a 2048-bit RSA key pair. You will share your public key with Gcashier Pay and keep your private key secret on your own infrastructure. Gcashier Pay uses your public key to verify the sign field on every inbound request.
# Step 1: Generate the raw 2048-bit private key
mkdir -p tmp
openssl genrsa -out tmp/tmp_rsa_private_key_2048.pem 2048

# Step 2: Convert to PKCS#8 format (required by the API)
openssl pkcs8 -topk8 \
  -in tmp/tmp_rsa_private_key_2048.pem \
  -out rsa_private_key_2048.pem \
  -nocrypt

# Step 3: Extract the public key
openssl rsa \
  -in tmp/tmp_rsa_private_key_2048.pem \
  -out rsa_public_key_2048.pem \
  -pubout
Never commit your private key (rsa_private_key_2048.pem) to source control or transmit it over any channel. If your private key is compromised, regenerate the key pair immediately and re-exchange the new public key with Gcashier Pay.
After running the commands, your working directory contains:
FilePurpose
rsa_private_key_2048.pemYour private key — keep this secret
rsa_public_key_2048.pemYour public key — share this with Gcashier Pay
3

Exchange public keys with Gcashier Pay

Send the contents of rsa_public_key_2048.pem to Gcashier Pay through the onboarding channel they provide. In return, Gcashier Pay gives you their RSA public key for the test environment.Store both keys so your integration code can load them at runtime:
  • Your private key → used to sign outgoing request payloads.
  • Gcashier Pay’s public key → used to encrypt the AES session key and to verify response signatures.
Public keys are environment-specific. The test environment key pair and the production key pair are different. Do not mix them up — using a production key against the sandbox (or vice versa) will cause decryption failures.
4

Download the demo SDK

Gcashier Pay provides a demo SDK that includes working encryption utilities, request builders, and sample calls for common API operations.

Download Demo SDK

starlinkDemo.zip — includes Java source, encryption helpers, and example API calls.
Extract the archive and open it in your IDE. The key files to review are:
  • RsaUtils — RSA sign / verify / encrypt / decrypt helpers.
  • AesUtils — AES/ECB/PKCS7Padding encrypt / decrypt helpers.
  • ApiClient — assembles the four POST parameters and executes the HTTPS call.
  • examples/ — ready-to-run samples for merchant access, FX, remittance, and payout APIs.
Load your key material into the SDK’s configuration before running any sample.
5

Build and encrypt your first request

The following example walks through the full encryption flow for a minimal request. Adapt it to your language of choice using the algorithm names as a guide.
import java.util.Base64;

// 1. Build the JSON plaintext
String jsonPlaintext = """
    {
      "head": {
        "version": "1.0.0",
        "tradeType": "00",
        "tradeTime": "1551341750",
        "tradeCode": "sp1301",
        "language": "cn"
      },
      "body": {
        "merchantNo": "YOUR_MERCHANT_NO"
      }
    }
    """;

// 2. Sign with your RSA private key → HEX string
String sign = RsaUtils.sign(
    jsonPlaintext,               // data to sign
    yourRsaPrivateKey,           // PKCS#8 private key
    "SHA1withRSA"                // algorithm
); // returns HEX-encoded signature

// 3. Generate a random AES session key
KeyGenerator kg = KeyGenerator.getInstance("AES");
kg.init(128);
SecretKey sk = kg.generateKey();
String skBase64 = Base64.getEncoder().encodeToString(sk.getEncoded());

// 4. Encrypt JSON plaintext with SK → Base64
String jsonEnc = AesUtils.encrypt(
    jsonPlaintext,   // plaintext
    skBase64,        // session key (Base64)
    "AES/ECB/PKCS5Padding"
); // returns Base64-encoded ciphertext

// 5. Encrypt SK with Gcashier Pay's RSA public key → HEX
String keyEnc = RsaUtils.encryptToHex(
    skBase64,                    // the Base64 session key
    gcashierPayRsaPublicKey,     // Gcashier Pay's public key
    "RSA/ECB/PKCS1Padding"
); // returns HEX-encoded encrypted session key

// 6. POST the four parameters
Map<String, String> body = Map.of(
    "merchantNo", "YOUR_MERCHANT_NO",
    "jsonEnc",    jsonEnc,
    "keyEnc",     keyEnc,
    "sign",       sign
);
HttpResponse response = httpClient.post(
    "https://{baseUrl}/api/YOUR_ENDPOINT",
    body
);
The AES session key only needs to be 128 bits for compatibility with the API. Use a cryptographically secure random generator — never derive the session key from a predictable value.
6

Verify the test environment response

A successful response arrives as the same four-field envelope (merchantNo, jsonEnc, keyEnc, sign). Decrypt and verify it by reversing the flow:
  1. HEX-decode keyEnc, then decrypt with your RSA private key using RSA/ECB/PKCS1Padding → recover the Base64 session key SK.
  2. Base64-decode jsonEnc and SK, then AES-decrypt → JSON plaintext.
  3. HEX-decode sign, then verify against the JSON plaintext using Gcashier Pay’s public key with SHA1withRSA.
Parse the decrypted JSON. A successful response looks like this:
{
  "head": {
    "version": "1.0.0",
    "tradeType": "01",
    "tradeTime": "1551341750",
    "tradeCode": "sp1301",
    "language": "cn",
    "respCode": "S00000",
    "respDesc": "Success"
  },
  "body": {}
}
respCode: "S00000" confirms the test environment received, decrypted, and processed your request successfully. Any other respCode value indicates an error — check the respDesc field for a human-readable description and review your encryption steps.
The {baseUrl} placeholder in all endpoint URLs is replaced with the actual hostname Gcashier Pay provides for each environment. See the Environments page for test and production base URL details.

​
What’s next

Now that you have a working encrypted request, explore the authentication reference for a deep dive into the full signing and encryption specification, or jump straight to the Environments page to understand the differences between sandbox and production.

Authentication

Full specification for the dual-key encryption scheme, POST parameters, and head fields.

Environments

How sandbox and production environments differ, and how mock testing rules work.