sp1401 Register a Beneficiary (Payee)

Before you can send funds to an external party, you must register them as a beneficiary using sp1401. This endpoint supports four payee types — overseas remittance, FX settlement, withdrawal, and internal Gcashier Pay account transfers. Because registration involves a compliance review, the API is asynchronous: you submit the payee details now, and the final approval or rejection is delivered to your callbackUrl via the sp3401 webhook. A successful synchronous response only confirms that your submission was received; monitor the webhook for the payeeId you will need in subsequent payment calls.

Endpoint

POST https://{baseUrl}/api/sp1401

Request Parameters

merOrderNo

string

required

Your unique merchant order number for this registration request. Maximum 10 characters.

operateType

string

Operation type. ADD creates a new payee (default); UPDATE modifies an existing payee. Maximum 10 characters.

payeeId

string

Conditionally required when operateType is UPDATE. The payee identifier originally returned by the sp3401 webhook. Maximum 50 characters.

payeeType

string

required

Classifies the intended use of the payee. Maximum 20 characters. Accepted values:

Value	Description
`OVERSEAS_PAYEE`	International remittance
`ESTIC_PAYEE`	FX settlement
`WITHDRAW_PAYEE`	Withdrawal
`ACCOUNT_PAYEE`	Internal Gcashier Pay account transfer

ownAcc

string

Conditionally required for certain payee types. Y indicates this is your own company account; N indicates a third-party payee. Defaults to N.

businessType

string

required

The trade business category code for this payee. Maximum 64 characters. Accepted values:

Code	Description
`10`	Logistics
`11`	Warehousing
`12`	Raw Materials
`13`	Ad Recommendation
`14`	Goods Procurement
`15`	Travel Procurement
`16`	Ad Services
`17`	Software Services
`18`	Pan-Entertainment
`19`	Other

businessDetail

array

Conditionally required when businessType is 14 (Goods Procurement) or 15 (Travel Procurement). Each element follows the BusinessDetail structure — refer to the Appendix for the full schema. Provide the specific commodity or service sub-codes relevant to the transaction.

countryCode

string

Conditionally required. ISO 3166-1 alpha-2 country code for the beneficiary’s country of residence. Maximum 2 characters.

address

string

Conditionally required. Full street address of the beneficiary. Maximum 256 characters.

payeeProvince

string

Conditionally required when bankCountry is CN. China region/province code for the payee. Maximum 50 characters.

payeeCity

string

Conditionally required when bankCountry is CN. City of the payee. Maximum 256 characters.

clearingType

string

Conditionally required. Clearing network for this payee. LOCAL uses the domestic clearing network of the destination country; SWIFT routes through the SWIFT network. Maximum 10 characters.

accountType

string

required

Type of the receiving account. Maximum 2 characters. Accepted values:

Value	Description
`00`	Individual
`01`	Enterprise
`03`	Gcashier Pay internal account

accountNo

string

Conditionally required. The beneficiary’s bank account number. Maximum 50 characters.

accountName

string

Conditionally required. The name on the receiving bank account. For individual accounts, format as lastName + firstName. Maximum 200 characters.

accountCurrency

string

Conditionally required. ISO 4217 three-letter currency code of the receiving account. Maximum 3 characters.

bankCountry

string

Conditionally required. ISO 3166-1 alpha-2 country code of the receiving bank. Maximum 2 characters.

bankName

string

required

Full legal name of the receiving bank. Maximum 24 characters.

bankAddress

string

Street address of the receiving bank branch. Maximum 256 characters.

swiftCode

string

SWIFT/BIC code of the receiving bank. Must be either 8 or 11 characters. Maximum 11 characters.

iban

string

Conditionally required for remittances to European region accounts. International Bank Account Number. Maximum 50 characters.

bankProvince

string

Conditionally required when bankCountry is US, AU, or a EUR-zone country and clearingType is LOCAL. Province or state of the receiving bank. Maximum 200 characters.

bankCity

string

Conditionally required under the same conditions as bankProvince. City of the receiving bank. Maximum 200 characters.

postCode

string

Conditionally required when bankCountry is US, AU, or a EUR-zone country. Postal code of the receiving bank. Maximum 200 characters.

routingCodeType1

string

Conditionally required for LOCAL clearing in certain corridors. Primary routing code type. Common values: aba (US ABA routing number), bank_code, bsb_code (AU), sort_code (UK), ifsc (IN).

routingCodeValue1

string

Conditionally required when routingCodeType1 is provided. The value corresponding to routingCodeType1.

routingCodeType2

string

Conditionally required for certain corridors that require a secondary routing identifier. Typically branch_code.

routingCodeValue2

string

Conditionally required when routingCodeType2 is provided. The value corresponding to routingCodeType2.

firstName

string

Conditionally required for individual payees (accountType = 00). Beneficiary’s given name. Maximum 32 characters.

lastName

string

Conditionally required for individual payees (accountType = 00). Beneficiary’s family name. Maximum 32 characters.

mobile

string

Conditionally required for individual payees. Beneficiary’s mobile phone number, including country code. Maximum 32 characters.

idType

string

Conditionally required for individual payees. Government-issued identity document type. Maximum 2 characters. Accepted values:

Value	Description
`01`	National ID Card
`02`	Passport
`03`	Taiwan Compatriot Permit

idcardNo

string

Conditionally required for individual payees. The document number corresponding to idType. Maximum 32 characters.

idcardFront

array

Conditionally required for individual payees. Array of upload paths for the front image of the identity document. Use the file path returned by the file upload endpoint (e.g., uploadFile/passport_front.png).

idcardBack

array

Conditionally required for individual payees. Array of upload paths for the back image of the identity document.

companyName

string

Conditionally required for enterprise payees (accountType = 01). Registered legal name of the company. Maximum 50 characters.

companyNo

string

Conditionally required for enterprise payees. Company registration or tax identification number. Maximum 50 characters.

licenseImg

array

Conditionally required for ESTIC_PAYEE enterprise accounts. Array of upload paths for the business license images.

relationProof

array

Conditionally required. Business-relationship supporting materials (e.g., contracts, invoices). Maximum 3 files. Provide upload paths returned by the file upload endpoint.

callbackUrl

string

required

The HTTPS endpoint on your platform where Gcashier Pay will deliver the sp3401 webhook notification upon completion of the compliance review. Maximum 255 characters.

Request Example

{
  "merOrderNo": "318216608947200",
  "operateType": "ADD",
  "payeeType": "OVERSEAS_PAYEE",
  "businessType": "14",
  "businessDetail": [
    {
      "businessType": "14",
      "child": [{ "code": "22", "name": "underwear" }]
    }
  ],
  "countryCode": "US",
  "address": "123 Fifth Avenue, New York, NY 10001",
  "clearingType": "SWIFT",
  "accountType": "00",
  "callbackUrl": "https://yourplatform.com/callback/payee",
  "bankName": "Citibank N.A.",
  "accountNo": "004401100035",
  "accountName": "JOHN DOE",
  "accountCurrency": "USD",
  "bankCountry": "US",
  "bankAddress": "388 Greenwich Street, New York, NY 10013",
  "swiftCode": "CITIUS33",
  "firstName": "John",
  "lastName": "Doe",
  "idType": "02",
  "idcardNo": "A12345678",
  "mobile": "12125551234",
  "idcardFront": ["uploadFile/passport_front.png"],
  "idcardBack": ["uploadFile/passport_back.png"],
  "relationProof": ["uploadFile/contract.pdf"]
}

Response Body

A respCode of S00000 confirms that your submission was accepted for review. The final outcome is delivered asynchronously via the sp3401 webhook.

merOrderNo

string

required

Your original merchant order number, echoed back for correlation.

bizFlowNo

string

required

Gcashier Pay’s internal flow reference number for this registration. Retain this value — you will need it to query status via sp2402.

status

string

required

Current registration status at the time of submission. Possible values:

Value	Description
`01`	Under Review
`03`	Rejected
`04`	Normal (Approved)

Response Example

{
  "merOrderNo": "318216608947200",
  "bizFlowNo": "64695022219410100019",
  "status": "01"
}

A status of 01 (Under Review) in the synchronous response is the expected result for new registrations. Do not re-submit the same payee — wait for the sp3401 webhook to deliver the final status and the payeeId you will use in payment requests.

​Endpoint

​Request Parameters

​Request Example

​Response Body

​Response Example

Endpoint

Request Parameters

Request Example

Response Body

Response Example