Skip to main content
Every Gcashier Pay API interaction — whether a payment initiation, a status query, or an FX conversion — uses the same two-layer JSON structure. The outer envelope is what travels over the wire and contains the encrypted payload alongside the keys needed to decrypt it. Inside that envelope, the inner JSON is divided into a head section that carries routing and protocol metadata, and a body section that carries the business-specific fields for each operation. Understanding this structure is essential before working with any individual API endpoint.

​
Outer Envelope vs Inner JSON

When you POST a request, the body your HTTP client sends looks like this: 
{
  "merchantNo": "M123456789",
  "jsonEnc":    "<Base64 AES ciphertext of the inner JSON>",
  "keyEnc":     "<HEX RSA-encrypted AES session key>",
  "sign":       "<HEX SHA1withRSA signature of the inner JSON>"
}
After Gcashier Pay decrypts jsonEnc, the revealed inner JSON always follows this shape: 
{
  "head": {
    "version":   "1.0.0",
    "tradeType": "00",
    "tradeTime": "1714000000",
    "tradeCode": "sp1301",
    "language":  "en"
  },
  "body": {
    // operation-specific fields documented on each endpoint page
  }
}

​
Request Head Fields

The head object in every outgoing request contains the following fields:
FieldTypeAttributeDescription
versionStringMProtocol version. Always "1.0.0".
tradeTypeStringMMessage type code. Always "00" for standard API requests.
tradeTimeStringMRequest timestamp as a 10-digit Unix epoch (seconds since 1970-01-01 UTC).
tradeCodeStringMThe operation code identifying which API action to perform (e.g. "sp1301" for a payment order). Each endpoint documents its own code.
languageStringMResponse language preference. Use "en" for English or "cn" for Chinese.
accessTokenStringCRequired for FX operations and other delegated flows. Omit for operations that do not need it.
Field attribute key used throughout this documentation:
  • M — Mandatory. Always include this field.
  • O — Optional. You may omit it; a sensible default or null applies.
  • C — Conditionally required. Required only when a specific condition is met, as described in each field’s notes.

​
Response Head Fields

Gcashier Pay adds two additional fields to the head when it returns a response:
FieldTypeAttributeDescription
versionStringMEchoed from the request.
tradeTypeStringMEchoed from the request.
tradeTimeStringMEchoed from the request.
tradeCodeStringMEchoed from the request.
languageStringMEchoed from the request.
respCodeStringMResult code. S00000 = success; S00001 = accepted and processing (async). Any other value indicates an error.
respDescStringMHuman-readable description of respCode, in the language you requested.

​
Standard Response Codes

CodeMeaning
S00000Success — the operation completed synchronously.
S00001Accepted — the operation has been queued and will complete asynchronously. Expect a webhook callback.
Any code other than these two indicates a failure. Refer to the error code reference for a full list.

​
Full Request Example

The following inner JSON is what you encrypt before sending. This example initiates a payment order (sp1301): 
{
  "head": {
    "version":   "1.0.0",
    "tradeType": "00",
    "tradeTime": "1714000000",
    "tradeCode": "sp1301",
    "language":  "en"
  },
  "body": {
    "orderNo":      "ORD-2024-00001",
    "currency":     "USD",
    "amount":       "100.00",
    "callbackUrl":  "https://yoursite.com/webhooks/gcashier",
    "description":  "Invoice #INV-001"
  }
}

​
Full Response Example

After Gcashier Pay processes the request, the decrypted inner JSON response looks like this: 
{
  "head": {
    "version":   "1.0.0",
    "tradeType": "00",
    "tradeTime": "1714000000",
    "tradeCode": "sp1301",
    "language":  "en",
    "respCode":  "S00001",
    "respDesc":  "Accepted"
  },
  "body": {
    "orderNo":    "ORD-2024-00001",
    "platformNo": "GC20240425000001",
    "status":     "PROCESSING"
  }
}
A respCode of S00001 means the order was accepted and is being processed. You will receive the final result via a webhook callback to the callbackUrl you provided in the request body.

​
Using accessToken for Delegated Operations

Certain operations — particularly FX trading — require an accessToken in the request head. The token identifies the sub-account or delegated authority under which the operation is performed. Obtain the token through the authentication flow before calling these endpoints. 
{
  "head": {
    "version":     "1.0.0",
    "tradeType":   "00",
    "tradeTime":   "1714001000",
    "tradeCode":   "sp2001",
    "language":    "en",
    "accessToken": "eyJhbGciOiJSUzI1NiJ9..."
  },
  "body": {
    "fromCurrency": "USD",
    "toCurrency":   "CNY",
    "amount":       "500.00"
  }
}
If an endpoint requires accessToken, its reference page will list the field with attribute C and describe exactly when it is required. Always check the individual endpoint documentation.