> ## 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.

# Request and Response Format for All API Calls

> Every Gcashier Pay API call carries an inner JSON packet with a standard head and a business-specific body, wrapped in an encrypted outer envelope.

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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.                                          |

<Note>
  **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.
</Note>

## 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`):

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

```json theme={null}
{
  "head": {
    "version":     "1.0.0",
    "tradeType":   "00",
    "tradeTime":   "1714001000",
    "tradeCode":   "sp2001",
    "language":    "en",
    "accessToken": "eyJhbGciOiJSUzI1NiJ9..."
  },
  "body": {
    "fromCurrency": "USD",
    "toCurrency":   "CNY",
    "amount":       "500.00"
  }
}
```

<Tip>
  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.
</Tip>