Skip to main content
Many Gcashier Pay operations are asynchronous: the platform accepts your request immediately (returning respCode: S00001) and then completes the work in the background. When the operation finishes, Gcashier Pay pushes the result to a webhook endpoint on your server. You register this endpoint by including a callbackUrl in the relevant API request body. Understanding how to receive, decrypt, and verify these callbacks is essential for building a reliable integration.

​
How Webhooks Work

Gcashier Pay sends webhook notifications as HTTPS POST requests to your callbackUrl. The POST body uses exactly the same four-field encrypted envelope as a standard API response: 
{
  "merchantNo": "M123456789",
  "jsonEnc":    "<Base64 AES ciphertext of the notification payload>",
  "keyEnc":     "<HEX RSA-encrypted AES session key>",
  "sign":       "<HEX SHA1withRSA signature>"
}
Decrypt and verify the callback using the same process described in Encryption & Signing: recover SK from keyEnc using your private key, decrypt jsonEnc with SK, then verify sign against the plaintext using Gcashier Pay’s public key.
Always verify the sign field before processing any callback. An invalid signature means the message did not originate from Gcashier Pay or has been tampered with. Discard such messages and log the event for investigation.

​
Responding to a Webhook

Your endpoint must return an HTTP 200 status code to acknowledge successful receipt of the callback. If Gcashier Pay does not receive a 200 response — due to a network error, timeout, or any non-200 status code from your server — it will retry the notification. Implement your handler to be idempotent: processing the same callback more than once must not cause duplicate actions (for example, duplicate fund movements or double-confirmed orders).
If you never receive a callback for an operation (for example, due to a prolonged outage), use the corresponding query API endpoint to check the operation’s status directly. Do not rely solely on callbacks for critical state transitions.

​
Webhook Event Codes

Each callback carries a tradeCode in its decrypted head that identifies the type of event. The table below lists all supported notification codes:
Trade CodeEvent
sp3101Merchant access (onboarding) result
sp3102Virtual account (VA) opening result
sp3103Trade receipt notification
sp3104Trade order application result
sp3105Flow-order association result
sp3201FX trading result
sp3301RMB payment result
sp3302International remittance result
sp3303Withdrawal result
sp3304Internal transfer result
sp3401Payee registration result

​
Setting Your callbackUrl

You register a callback URL per-request, not as a global setting. Include a callbackUrl field in the body of any request that triggers an asynchronous operation. Gcashier Pay will POST the result notification to that URL when the operation completes. 
{
  "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"
  }
}
Use a unique, versioned path for your webhook endpoint (e.g. /webhooks/gcashier/v1) so you can roll out handler changes without disrupting in-flight notifications. Ensure your endpoint is publicly reachable over HTTPS — Gcashier Pay cannot deliver callbacks to private or localhost URLs.

​
Webhook Processing Checklist

Use the following checklist when implementing your webhook handler:
1

Parse the outer envelope

Read the POST body as JSON and extract merchantNo, jsonEnc, keyEnc, and sign.
2

Decrypt the payload

HEX-decode keyEnc, RSA-decrypt with your private key to recover the AES session key SK. Base64-decode jsonEnc and decrypt with SK (AES/ECB/PKCS7Padding) to obtain the inner JSON plaintext.
3

Verify the signature

HEX-decode sign and verify it against the inner JSON plaintext using Gcashier Pay’s public key (SHA1withRSA). Reject and log any message that fails verification.
4

Inspect the tradeCode

Read head.tradeCode from the decrypted JSON to determine which event type you received, then route the body to the appropriate handler.
5

Process idempotently

Check whether you have already processed this event (for example, by recording the order or transaction number). If you have, skip reprocessing and return 200 immediately.
6

Return HTTP 200

Respond with a 200 status code. Any other status or a connection timeout will trigger a retry from Gcashier Pay.