> ## 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.
# Send International Remittances via Gcashier Pay
> Register an overseas payee, lock in a remittance rate, confirm the transfer, and track settlement — a complete guide to Gcashier Pay cross-border remittances.
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.
Lock in a rate specifying either the debit amount or the arrival amount.
Execute the transfer using the `quoteId` before it expires.
Gcashier Pay posts the final `SUCC` or `FAIL` status to your callback URL.
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`.
```json sp1401 Request — Overseas Payee theme={null}
{
"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"
}
```
```json sp1401 Response theme={null}
{
"bizFlowNo": "BF20240601000801",
"code": "S00001",
"message": "Overseas payee registration submitted and under review."
}
```
### sp3401 Webhook — Payee Approval Result
```json sp3401 Webhook — Approved theme={null}
{
"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
```json sp1302 Request — Lock Arrival Amount theme={null}
{
"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"
}
```
```json sp1302 Response theme={null}
{
"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.
```json sp1303 Request theme={null}
{
"quoteId": "QT20240601000901",
"callbackUrl": "https://api.acme-trade.com/webhooks/gcashier/remittance-result"
}
```
```json sp1303 Response theme={null}
{
"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.
```json sp3302 Webhook — Success theme={null}
{
"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"
}
```
```json sp3302 Webhook — Failed theme={null}
{
"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.
```json sp2302 Request — by quoteId theme={null}
{
"quoteId": "QT20240601000901"
}
```
```json sp2302 Request — by time range theme={null}
{
"startTime": "2024-06-01 00:00:00",
"endTime": "2024-06-30 23:59:59"
}
```
```json sp2302 Response theme={null}
{
"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.