Send International Remittances via Gcashier Pay

Gcashier Pay’s international remittance API lets you send funds to overseas bank accounts in local currencies across a wide range of corridors. Like currency exchange, remittances follow a two-step quote-and-confirm pattern: you first call sp1302 to get a locked rate and a quoteId, then confirm the transfer with sp1303 before the quote expires. Before you can send any remittance, the destination account must be registered as an overseas payee via sp1401.

Overview

Submit the beneficiary’s bank account details for compliance review.

Get a remittance quote (sp1302)

Lock in a rate specifying either the debit amount or the arrival amount.

Confirm the remittance (sp1303)

Execute the transfer using the quoteId before it expires.

Receive the result webhook (sp3302)

Gcashier Pay posts the final SUCC or FAIL status to your callback URL.

Query remittance history (sp2302)

Look up past transfers by quoteId, order reference, or time range.

Step 1 — Register an Overseas Payee

Call POST /api/sp1401 with payeeType set to OVERSEAS_PAYEE to register the beneficiary’s bank account. Gcashier Pay’s compliance team reviews the registration before issuing a payeeId.

{
  "merOrderNo": "PAYEE20240601010",
  "payeeType": "OVERSEAS_PAYEE",
  "payeeName": "Beijing Supplier Ltd",
  "bankName": "Industrial and Commercial Bank of China",
  "bankAccountNo": "6222021234567890123",
  "swiftCode": "ICBKCNBJ",
  "currency": "CNY",
  "countryCode": "CN",
  "bankAddress": "55 Fuxingmennei Avenue, Xicheng District, Beijing 100032",
  "payeeAddress": "Building A, 10 Zhongguancun Street, Haidian District, Beijing",
  "callbackUrl": "https://api.acme-trade.com/webhooks/gcashier/payee-result"
}

{
  "bizFlowNo": "BF20240601000801",
  "code": "S00001",
  "message": "Overseas payee registration submitted and under review."
}

sp3401 Webhook — Payee Approval Result

{
  "bizFlowNo": "BF20240601000801",
  "merOrderNo": "PAYEE20240601010",
  "code": "S00000",
  "message": "Overseas payee approved.",
  "payeeId": "PYE0000567",
  "payeeName": "Beijing Supplier Ltd",
  "status": "ACTIVE"
}

Store the payeeId securely — you’ll need it for every remittance to this beneficiary.

Step 2 — Get a Remittance Quote

Call POST /api/sp1302 to lock in a remittance rate. You can specify either the debitAmount (how much you want to send from your balance) or the arriveAmount (how much the beneficiary must receive). If you provide both, arriveAmount takes precedence.

Field	Required	Description
`merOrderNo`	M	Your unique reference for this remittance
`arriveCurrency`	M	Currency the beneficiary receives
`debitCurrency`	M	Currency debited from your Gcashier Pay balance
`payType`	O	`LOCAL` for local bank rails; `SWIFT` for international SWIFT network
`feeDirection`	C (SWIFT only)	`SHA` = fees shared; `OUR` = you bear all fees
`accountType`	M	`1` = bank account
`debitAmount`	C	Amount to debit (required if `arriveAmount` not provided)
`arriveAmount`	C	Amount beneficiary receives (takes precedence over `debitAmount`)
`purpose`	M	Payment purpose code (1–31 or 99; see Purpose Codes section)
`payeeId`	M	Approved payee identifier from sp3401
`poboFlag`	O	Payment on behalf of indicator
`tradeComments`	O	Free-text trade description
`purposeRemark`	O	Additional remarks for custom purpose code 99

Request / Response Example

{
  "merOrderNo": "REM20240601001",
  "arriveCurrency": "CNY",
  "debitCurrency": "USD",
  "payType": "SWIFT",
  "feeDirection": "SHA",
  "accountType": "1",
  "arriveAmount": "72000.00",
  "purpose": "1",
  "payeeId": "PYE0000567",
  "tradeComments": "Payment for goods - Invoice INV-2024-0601"
}

{
  "merOrderNo": "REM20240601001",
  "debitCurrency": "USD",
  "arriveCurrency": "CNY",
  "rate": "7.2201",
  "debitAmount": "9972.30",
  "arriveAmount": "72000.00",
  "quoteId": "QT20240601000901",
  "expireTime": "1717229100000"
}

The expireTime is a Unix timestamp in milliseconds. Quotes expire quickly (typically within 30 seconds). Call sp1303 immediately after receiving the quote to avoid expiry.

debitAmount vs arriveAmount

Use debitAmount when you know exactly how much you want to spend from your balance and you accept the resulting arrival amount.
Use arriveAmount when the beneficiary must receive a precise amount (e.g., to settle a specific invoice in their local currency). If you supply both fields, arriveAmount always takes precedence.

Step 3 — Confirm the Remittance

Once you have a valid quoteId, call POST /api/sp1303 to execute the transfer. The synchronous response confirms acceptance; the definitive settlement result arrives via webhook.

{
  "quoteId": "QT20240601000901",
  "callbackUrl": "https://api.acme-trade.com/webhooks/gcashier/remittance-result"
}

{
  "quoteId": "QT20240601000901",
  "bizFlow": "BF20240601000902",
  "merOrderNo": "REM20240601001",
  "countryCode": "CN",
  "arriveCurrency": "CNY",
  "debitCurrency": "USD",
  "payType": "SWIFT",
  "accountType": "1",
  "arriveAmount": "72000.00",
  "debitAmount": "9972.30",
  "rate": "7.2201",
  "status": "PROCESS",
  "code": "S00001",
  "message": "Remittance confirmed and processing."
}

A status of PROCESS is the expected initial state. Your bizFlow is the tracking reference for all subsequent queries and webhook correlation.

Step 4 — Receive the Result Webhook (sp3302)

Gcashier Pay posts the final settlement outcome to your callbackUrl once the transfer is completed or rejected. Return HTTP 200 to acknowledge receipt.

{
  "bizFlow": "BF20240601000902",
  "quoteId": "QT20240601000901",
  "merOrderNo": "REM20240601001",
  "payeeId": "PYE0000567",
  "arriveCurrency": "CNY",
  "debitCurrency": "USD",
  "arriveAmount": "72000.00",
  "debitAmount": "9972.30",
  "rate": "7.2201",
  "status": "SUCC",
  "code": "S00000",
  "message": "Remittance completed. Funds credited to beneficiary.",
  "completedTime": "2024-06-01 18:22:45"
}

{
  "bizFlow": "BF20240601000902",
  "quoteId": "QT20240601000901",
  "merOrderNo": "REM20240601001",
  "payeeId": "PYE0000567",
  "status": "FAIL",
  "code": "E00031",
  "message": "Remittance failed: beneficiary bank account closed.",
  "completedTime": "2024-06-01 18:23:10"
}

Status	Meaning
`SUCC`	Funds have been credited to the beneficiary’s account
`FAIL`	Transfer failed — debited amount has been refunded to your balance

Step 5 — Query Remittance History

Use POST /api/sp2302 to retrieve past remittance records. You can query by quoteId, merOrderNo, or a time range.

{
  "quoteId": "QT20240601000901"
}

{
  "startTime": "2024-06-01 00:00:00",
  "endTime": "2024-06-30 23:59:59"
}

{
  "code": "S00000",
  "message": "success",
  "data": [
    {
      "bizFlow": "BF20240601000902",
      "quoteId": "QT20240601000901",
      "merOrderNo": "REM20240601001",
      "payeeId": "PYE0000567",
      "arriveCurrency": "CNY",
      "debitCurrency": "USD",
      "arriveAmount": "72000.00",
      "debitAmount": "9972.30",
      "rate": "7.2201",
      "payType": "SWIFT",
      "status": "SUCC",
      "completedTime": "2024-06-01 18:22:45"
    }
  ]
}

Payment Purpose Codes

The purpose field is mandatory on every remittance. Select the code that best describes the underlying transaction:

Code	Purpose
`1`	Payment for goods
`2`	Payment for services
`3`	Dividend / profit repatriation
`4`	Loan repayment
`5`	Capital injection
`6`	Royalties and licensing fees
`7`	Rental payment
`8`	Consulting fees
`9`	Construction and engineering services
`10`	Insurance premium
`11`	Freight and transport
`12`	Travel and accommodation
`13`	Education fees
`14`	Medical services
`15`	Software and IT services
`16`	Financial services
`17`	Advertising and marketing
`18`	Personal remittance
`19`	Salary and wages
`20`	Commission fees
`21`	Research and development
`22`	Legal and professional fees
`23`	Membership and subscription fees
`24`	E-commerce platform settlement
`25`	Maintenance and repair services
`26`	Telecommunications services
`27`	Cultural and sporting activities
`28`	Government payment
`29`	Donation and aid
`30`	Intellectual property acquisition
`31`	Real estate acquisition
`99`	Other — provide details in `purposeRemark`

When using purpose code 99, the purposeRemark field becomes mandatory. Provide a clear English description of the payment purpose to avoid compliance delays.

SWIFT Fee Direction

When payType is SWIFT, you must specify feeDirection to determine how correspondent bank charges are allocated:

Value	Who pays correspondent bank fees
`SHA`	Shared — you pay the sending bank’s fees; the beneficiary pays receiving bank fees. The beneficiary may receive slightly less than `arriveAmount`.
`OUR`	You bear all — you cover all fees end-to-end. The beneficiary receives the full `arriveAmount`.

Use OUR when settling invoices for a precise amount — this guarantees the beneficiary receives exactly what you specified. Use SHA for general transfers where a small fee deduction on arrival is acceptable.

Sandbox Testing

In the Gcashier Pay sandbox, the remittance outcome is determined by a single digit of the amount in your sp1302 request:

Single digit of `amount`	Simulated result
`0` – `3`	`SUCC` — remittance completes successfully
`4` – `6`	`FAIL` — remittance rejected
`7` – `9`	No action — transfer stays in `PROCESS` state

For example, an arriveAmount of 72000.00 (last non-zero digit relevant for testing) — use amounts like 1000.00, 2000.00, or 3000.00 to reliably trigger success in the sandbox.

Getting Started

Core Concepts

Guides

Send International Remittances via Gcashier Pay

Overview

Step 1 — Register an Overseas Payee

sp3401 Webhook — Payee Approval Result

Step 2 — Get a Remittance Quote

Request / Response Example

debitAmount vs arriveAmount

Step 3 — Confirm the Remittance

Step 4 — Receive the Result Webhook (sp3302)

Step 5 — Query Remittance History

Payment Purpose Codes

SWIFT Fee Direction

Sandbox Testing

​Overview

​Step 1 — Register an Overseas Payee

​sp3401 Webhook — Payee Approval Result

​Step 2 — Get a Remittance Quote

​Request / Response Example

​debitAmount vs arriveAmount

​Step 3 — Confirm the Remittance

​Step 4 — Receive the Result Webhook (sp3302)

​Step 5 — Query Remittance History

​Payment Purpose Codes

​SWIFT Fee Direction

​Sandbox Testing

Overview

Step 1 — Register an Overseas Payee

sp3401 Webhook — Payee Approval Result

Step 2 — Get a Remittance Quote

Request / Response Example

debitAmount vs arriveAmount

Step 3 — Confirm the Remittance

Step 4 — Receive the Result Webhook (sp3302)

Step 5 — Query Remittance History

Payment Purpose Codes

SWIFT Fee Direction

Sandbox Testing