Request and Response Format for All API Calls

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:

Field	Type	Attribute	Description
`version`	String	M	Protocol version. Always `"1.0.0"`.
`tradeType`	String	M	Message type code. Always `"00"` for standard API requests.
`tradeTime`	String	M	Request timestamp as a 10-digit Unix epoch (seconds since 1970-01-01 UTC).
`tradeCode`	String	M	The operation code identifying which API action to perform (e.g. `"sp1301"` for a payment order). Each endpoint documents its own code.
`language`	String	M	Response language preference. Use `"en"` for English or `"cn"` for Chinese.
`accessToken`	String	C	Required 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:

Field	Type	Attribute	Description
`version`	String	M	Echoed from the request.
`tradeType`	String	M	Echoed from the request.
`tradeTime`	String	M	Echoed from the request.
`tradeCode`	String	M	Echoed from the request.
`language`	String	M	Echoed from the request.
`respCode`	String	M	Result code. `S00000` = success; `S00001` = accepted and processing (async). Any other value indicates an error.
`respDesc`	String	M	Human-readable description of `respCode`, in the language you requested.

Standard Response Codes

Code	Meaning
`S00000`	Success — the operation completed synchronously.
`S00001`	Accepted — 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.

Getting Started

Core Concepts

Guides

Request and Response Format for All API Calls

Outer Envelope vs Inner JSON

Request Head Fields

Response Head Fields

Standard Response Codes

Full Request Example

Full Response Example

Using accessToken for Delegated Operations

​Outer Envelope vs Inner JSON

​Request Head Fields

​Response Head Fields

​Standard Response Codes

​Full Request Example

​Full Response Example

​Using accessToken for Delegated Operations

Outer Envelope vs Inner JSON

Request Head Fields

Response Head Fields

Standard Response Codes

Full Request Example

Full Response Example

Using accessToken for Delegated Operations