> ## Documentation Index
> Fetch the complete documentation index at: https://developer.gcashier.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gcashier Pay Communication Protocol Overview

> Gcashier Pay uses HTTPS 1.2 with JSON payloads and end-to-end encryption for every message exchanged between merchants and the platform.

All communication between your application and Gcashier Pay takes place over HTTPS 1.2, with JSON as the data interchange format and UTF-8 as the required character encoding. Every message — in both directions — is fully encrypted before transmission. There are no plaintext API calls; if a message arrives or is sent without encryption it will be rejected. This ciphertext-only policy ensures that sensitive financial data is protected both in transit and against replay attacks.

## Communication Model

Gcashier Pay operates a **bidirectional** communication model:

* **Merchant → Gcashier Pay:** Your server initiates API requests (payments, queries, FX operations, etc.) by POSTing an encrypted envelope to a Gcashier Pay endpoint.
* **Gcashier Pay → Merchant:** Gcashier Pay initiates asynchronous webhook notifications back to a `callbackUrl` you provide, using the identical encrypted envelope format. You must implement an HTTPS endpoint capable of receiving these callbacks.

Every HTTP request and response sets `Content-Type: application/json` and encodes all string data in UTF-8.

<Note>
  Both request and response bodies are JSON objects. Even error responses follow the standard encrypted envelope structure — never return or expect raw error strings outside the envelope.
</Note>

## Outer POST Envelope

Every API call — whether merchant-originated or platform-initiated — is wrapped in the same four-field JSON envelope. This envelope is what actually travels over the wire; the real business payload lives inside `jsonEnc` after decryption.

| Field        | Type   | Required | Description                                                                                                                                     |
| ------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchantNo` | String | M        | Your unique merchant identifier assigned by Gcashier Pay. Identifies whose keys should be used for decryption and verification.                 |
| `jsonEnc`    | String | M        | The Base64-encoded AES-encrypted ciphertext of the inner JSON payload (containing `head` and `body`).                                           |
| `keyEnc`     | String | M        | The HEX-encoded RSA-encrypted AES session key. The recipient decrypts this first to recover the session key, then uses it to decrypt `jsonEnc`. |
| `sign`       | String | M        | The HEX-encoded SHA1withRSA digital signature over the inner JSON plaintext, signed with the sender's RSA private key.                          |

<Tip>
  The `merchantNo` field sits outside encryption intentionally — Gcashier Pay uses it to look up the correct RSA public key before it can decrypt anything else. Ensure it is always accurate.
</Tip>

## Transport Requirements

* **Protocol:** HTTPS 1.2 (TLS 1.2 or higher). Plain HTTP connections are not accepted.
* **Method:** `POST` for all endpoints, including webhook callbacks.
* **Content-Type:** `application/json` on every request and response.
* **Encoding:** UTF-8 for all string values before encryption.
* **Endpoint base URL:** Provided by Gcashier Pay during merchant onboarding for both production and sandbox environments.

<Warning>
  Do not attempt to send unencrypted JSON directly to any Gcashier Pay endpoint. All requests must be wrapped in the four-field encrypted envelope described above, or the platform will return an error.
</Warning>