Gcashier Pay API Response Codes and Error Handling

Every response from the Gcashier Pay API includes a head.respCode field that tells you the immediate outcome of your request. Because many operations — such as remittances, FX trades, and merchant onboarding — are processed asynchronously, understanding the difference between a synchronous success code and an async acceptance code is essential for building a reliable integration.

Response Code Reference

The table below lists the core response codes you will encounter across Gcashier Pay APIs.

Code	Meaning	What to do
`S00000`	Success — The request was accepted and completed synchronously.	No further action is required for this request.
`S00001`	Accepted / Processing — The request was received and queued for async processing.	Wait for the webhook callback to your `callbackUrl`. If it does not arrive within the expected window, poll using the appropriate query API (sp2x series).
`AR0021`	Insufficient balance — Your account does not hold enough funds to complete the operation (commonly returned from FX history queries when a trade cannot execute).	Top up your account balance and retry, or adjust the trade amount.
`80000`	Additional materials required — The submission is on hold pending supplementary documentation.	Re-submit via sp1102 with the `addMaterial` flag set to `1` and attach the requested documents.

Invocation Modes

Gcashier Pay APIs operate in two distinct modes. You need to handle each one differently in your integration.

Real-Time Interface
Notification / Webhook API

A real-time interface returns a response immediately in the HTTP reply body. The result is definitive at the moment you receive it.

S00000 — The operation is complete. You can act on the result right away.
S00001 — The platform has accepted your request but the operation is still being processed. You will receive the final outcome via a webhook callback posted to your callbackUrl. Do not treat S00001 as a failure.

{
  "head": {
    "respCode": "S00001",
    "respMsg": "Accepted"
  },
  "body": {
    "bizFlow": "BF20240601123456",
    "merOrderNo": "ORD-20240601-001"
  }
}

Store the bizFlow and merOrderNo values returned in the body — you will need them to match incoming callbacks and to query status manually if necessary.

For async operations, Gcashier Pay POSTs a notification to the callbackUrl you supplied in the original request once processing is complete.

Your endpoint must return an HTTP 200 OK response to acknowledge receipt. Any other status code causes the platform to retry delivery.
Always verify the sign field in the callback payload before you process it. Callbacks with an invalid signature must be rejected.
If your endpoint is temporarily unavailable, Gcashier Pay retries the notification according to its retry schedule — keep your callback URL highly available.

{
  "head": {
    "respCode": "S00000",
    "sign": "<computed_signature>"
  },
  "body": {
    "bizFlow": "BF20240601123456",
    "merOrderNo": "ORD-20240601-001",
    "status": "SUCCESS"
  }
}

Handling Missing Callbacks

If a callback does not arrive within the expected time window (typically 5–10 minutes for most operations), do not assume the transaction failed. Instead, query the platform directly using the corresponding sp2x query API:

Original Operation	Query API
Merchant access application	sp2101
FX trade	sp2201
International remittance	sp2301
RMB payment	sp2302
Withdrawal	sp2303
Account flow / statement	sp2404

Pass the bizFlow or merOrderNo you stored from the original response to retrieve the current status.

Error Handling Best Practices

Follow these guidelines to build a resilient integration with Gcashier Pay:

Verify every webhook signature. Compute the expected sign value using your secret key and reject any callback where the signature does not match. This protects you from spoofed notifications.
Treat S00001 as pending, not failed. Many cross-border payment operations take seconds to minutes to settle. Poll via the query APIs if your webhook does not arrive within the expected window rather than retrying the original submission.
Store bizFlow and merOrderNo immediately. Persist these identifiers in your database as soon as you receive the initial response. They are your keys for querying status, reconciling settlements, and raising support cases.
Keep your callbackUrl highly available. Deploy your callback endpoint with redundancy and ensure it responds within your platform’s SLA. A slow or unavailable callback URL will delay notification delivery and can complicate reconciliation.
Handle 80000 by re-submitting with additional materials. When you receive this code for an onboarding or KYC submission, gather the requested documents and re-submit using sp1102 with addMaterial=1. Do not create a new application.
Do not retry on AR0021. An insufficient-balance error will not resolve itself on retry. Top up the relevant account or reduce the trade amount before attempting the operation again.

​Response Code Reference

​Invocation Modes

​Handling Missing Callbacks

​Error Handling Best Practices

Response Code Reference

Invocation Modes

Handling Missing Callbacks

Error Handling Best Practices