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
Register an overseas payee (sp1401)
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.
Receive the result webhook (sp3302)
Gcashier Pay posts the final
SUCC or FAIL status to your callback URL.Step 1 — Register an Overseas Payee
Call POST /api/sp1401 withpayeeType set to OVERSEAS_PAYEE to register the beneficiary’s bank account. Gcashier Pay’s compliance team reviews the registration before issuing a payeeId.
sp3401 Webhook — Payee Approval Result
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 thedebitAmount (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
debitAmount vs arriveAmount
- Use
debitAmountwhen you know exactly how much you want to spend from your balance and you accept the resulting arrival amount. - Use
arriveAmountwhen the beneficiary must receive a precise amount (e.g., to settle a specific invoice in their local currency). If you supply both fields,arriveAmountalways takes precedence.
Step 3 — Confirm the Remittance
Once you have a validquoteId, call POST /api/sp1303 to execute the transfer. The synchronous response confirms acceptance; the definitive settlement result arrives via webhook.
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 yourcallbackUrl once the transfer is completed or rejected. Return HTTP 200 to acknowledge receipt.
| 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 byquoteId, merOrderNo, or a time range.
Payment Purpose Codes
Thepurpose 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
WhenpayType 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. |
Sandbox Testing
In the Gcashier Pay sandbox, the remittance outcome is determined by a single digit of theamount 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 |
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.