Skip to main content
Every message exchanged with Gcashier Pay is both encrypted and digitally signed. Encryption guarantees that only the intended recipient can read the payload — even if it is intercepted in transit. Signing guarantees authenticity: the recipient can verify that the message genuinely came from the claimed sender and has not been tampered with. Both protections are mandatory on every request and response; neither is optional.

​
Cryptographic Algorithms

PurposeAlgorithm
Symmetric payload encryptionAES/ECB/PKCS7Padding
Session key encryptionRSA/ECB/PKCS1Padding
Session key generationJava KeyGenerator (or equivalent)
Digital signatureSHA1withRSA
Key encoding in envelopekeyEnc → HEX; jsonEnc → Base64; sign → HEX

​
Key Exchange Overview

The security model depends on each party holding an RSA key pair:
  • You (merchant): Generate your own RSA key pair. Keep your private key secret on your servers. Provide your public key to Gcashier Pay during onboarding.
  • Gcashier Pay: Provides you with its public key. Gcashier Pay holds the corresponding private key internally.
When you send a request, you sign with your private key and encrypt the session key with Gcashier Pay’s public key. When Gcashier Pay sends you a webhook, it signs with its private key and encrypts the session key with your public key.

​
Outgoing Message: Encryption & Signing Flow

When you send a request to Gcashier Pay, follow these steps in order:
1

Compose the inner JSON plaintext

Build the complete inner JSON object (containing head and body) as a UTF-8 string. This is the plaintext you will sign and then encrypt.
2

Sign the plaintext

Sign the UTF-8 JSON string with your RSA private key using the SHA1withRSA algorithm. Encode the resulting signature bytes as a HEX string — this becomes the sign field.
3

Generate an AES session key

Use a cryptographically secure key generator (e.g., Java’s KeyGenerator for AES) to produce a random AES session key for this request. Encode the raw key bytes as Base64 — this is your intermediate SK.
4

Encrypt the JSON payload

Encrypt the UTF-8 JSON plaintext using SK with AES/ECB/PKCS7Padding. Encode the resulting ciphertext as Base64 — this becomes the jsonEnc field.
5

Encrypt the session key

Encrypt SK (the Base64 string) using Gcashier Pay’s RSA public key with RSA/ECB/PKCS1Padding. Encode the result as a HEX string — this becomes the keyEnc field.
6

Assemble and POST the envelope

Combine all four fields into the outer envelope and POST it as JSON:
{
  "merchantNo": "your-merchant-number",
  "jsonEnc":    "<Base64-encoded AES ciphertext>",
  "keyEnc":     "<HEX-encoded RSA-encrypted session key>",
  "sign":       "<HEX-encoded SHA1withRSA signature>"
}

​
Incoming Message: Decryption & Verification Flow

When you receive a response from Gcashier Pay or a webhook callback, reverse the process:
1

Extract the envelope fields

Parse the incoming JSON body and retrieve jsonEnc, keyEnc, and sign.
2

Recover the AES session key

HEX-decode keyEnc to get the encrypted session key bytes. Decrypt those bytes using your RSA private key with RSA/ECB/PKCS1Padding to recover the Base64-encoded SK.
3

Decrypt the payload

Base64-decode both jsonEnc and SK. Use SK to AES-decrypt the ciphertext with AES/ECB/PKCS7Padding and UTF-8 decode the result to obtain the inner JSON plaintext.
4

Verify the signature

HEX-decode sign to get the signature bytes. Verify those bytes against the inner JSON plaintext string using Gcashier Pay’s RSA public key and the SHA1withRSA algorithm. If verification fails, discard the message immediately.
Always verify the signature after decryption, before acting on any field in the payload. Processing a message with an invalid signature could expose your system to forged callbacks or tampered responses.

​
Generating Your RSA Key Pair

You need a 2048-bit RSA key pair. Generate one using either of the methods below.

​
Windows

Download the Gcashier Pay RSA key-generation tool and follow the instructions bundled with it. The tool outputs a PKCS#8 private key file and a matching public key file.

​
macOS / Linux (OpenSSL)

Run the following three commands in sequence. The intermediate file in tmp/ is the raw RSA key; the final files are the formatted PKCS#8 private key and the X.509 public key you provide to Gcashier Pay. 
# Step 1 – Generate a 2048-bit RSA key (intermediate)
openssl genrsa -out tmp/tmp_rsa_private_key_2048.pem 2048

# Step 2 – Convert to PKCS#8 format (your actual private key — keep this secret)
openssl pkcs8 -topk8 \
  -in  tmp/tmp_rsa_private_key_2048.pem \
  -out rsa_private_key_2048.pem \
  -nocrypt

# Step 3 – Extract the public key (share this with Gcashier Pay)
openssl rsa \
  -in  tmp/tmp_rsa_private_key_2048.pem \
  -out rsa_public_key_2048.pem \
  -pubout
After running these commands:
  • rsa_private_key_2048.pem — your PKCS#8 private key. Never share or commit this file.
  • rsa_public_key_2048.pem — your public key. Submit this to Gcashier Pay during onboarding.
Gcashier Pay will send you its own public key (gcashier_public_key.pem or equivalent) after onboarding is complete. Store it securely; you need it to encrypt outgoing session keys and to verify incoming signatures.

​
Demo SDK

Gcashier Pay provides a reference implementation demonstrating the full encryption, signing, decryption, and verification flow. Download the demo SDK to explore working code examples: Download starlinkDemo.zip The demo includes sample key pairs, utility classes for each cryptographic step, and end-to-end integration tests you can run against the sandbox environment.