Register a Beneficiary

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

Enterprise receiver’s bank account and company information(when enterprise is required).

Show enterprise receiver fields

string

required

Your unique merchant order number for this deletion request. This value is used for idempotency — submitting the same merOrderNo twice will not delete the payee a second time.

string

required

bank country code (e.g. US) ISO 3166-1 alpha-2.

string

required

ISO 4217 3-letter currency code (e.g. USD). Omit this field to retrieve balances for all currencies.

string

required

paymentMode value is LOCAL or SWIFT.

string

payoutType value is WALLET, BANK(Optional).

string

required

payoutMethod value from List PayoutMethod API, when value SWIFT is WIRE.

string

required

Business mode. Must be B for enterprise.

string

required

Bank account number.

string

Bank code. Rules:

For LOCAL: required when payoutMethod is not WECHAT or ALIPAY. Also required when bankCountry is CN, BR, or IN (in which case branchCode is also required).
For SWIFT: not required (use bankName instead).

string

Bank name.

string

Branch code.

string

Correspondent bank name. Optional, SWIFT only. Either provide all three proxy bank fields or none.

string

Correspondent bank address. Optional, SWIFT only.

string

Correspondent bank SWIFT code. Optional, SWIFT only.

string

SWIFT/BIC code of the receiver’s bank. Required when settlementNetwork is SWIFT.

string

required

Country where the receiver’s company is registered.

string

required

Company name.

string

Local Company name.

string

Company email address (optional).

string

Phone area code. Required when bankCountry is BR, KR, MA, or IN. See the phone code dictionary.

string

Phone number (optional).

string

required

Country of business address. See the country dictionary.

string

required

State or province. Use the English name for non-CN countries. Use the province/city code for CN. See the dictionary.

string

required

City.

string

required

Street address.

string

Postal code (optional).

string

ifsc Code.

string

cnaps.

string

tax id number.

string

Business license image (optional). Applicable for CN.

string

Business registration certificate image (optional). Applicable for HK.

string

Certificate of incorporation image (optional). Applicable for non-CN and HK.

array

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

string

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

Individual receiver’s bank account and identity information(when individual is required).

Show individual receiver fields

string

required

Your unique merchant order number for this deletion request. This value is used for idempotency — submitting the same merOrderNo twice will not delete the payee a second time.

string

required

bank country code (e.g. US) ISO 3166-1 alpha-2.

string

required

ISO 4217 3-letter currency code (e.g. USD). Omit this field to retrieve balances for all currencies.

string

required

paymentMode value is LOCAL or SWIFT.

string

payoutType value is WALLET, BANK(Optional).

string

required

payoutMethod value from List PayoutMethod API, when value SWIFT is WIRE.

string

required

Business mode. Must be C for individual.

string

required

Bank account number.

string

Bank code. Rules:

For LOCAL: required when payoutMethod is not WECHAT or ALIPAY. Also required when bankCountry is CN, BR, or IN (in which case branchCode is also required).
For SWIFT: not required (use bankName instead).

string

Bank name.

string

Branch code.

string

Correspondent bank name. Optional, SWIFT only. Either provide all three proxy bank fields or none.

string

Correspondent bank address. Optional, SWIFT only.

string

Correspondent bank SWIFT code. Optional, SWIFT only.

string

SWIFT/BIC code of the receiver’s bank. Required when settlementNetwork is SWIFT.

string

required

ID document type. 01 = National ID card, 02 = Passport.

string

required

ID document number.

string

required

English first name.

string

required

English last name.

string

required

Date of birth. Format: YYYY-MM-DD.

string

required

Place of birth. See the country dictionary.

string

required

Nationality. See the country dictionary.

string

required

Gender. M = Male, F = Female, X = Other.

string

Email address (optional).

string

Phone area code. Required when bankCountry is BR, KR, MA, or IN. See the phone code dictionary.

string

Phone number (optional).

string

required

Country of residence. See the country dictionary.

string

required

State or province. Use the English name for non-CN countries. Use the province/city code for CN. See the dictionary.

string

required

City.

string

required

Street address. Allowed characters: ^[a-zA-Z0-9\s.,!?:;'"()\[\]{}/*\\-]+$

string

Postal code (optional).

string

ifsc Code.

string

cnaps.

string

tax id number.

string

National emblem side of the ID card, or passport photo page.

string

Portrait side of the ID card. Required when idType is 01.

array

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

string

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": "L0000011782371689504",
	"countryCode": "IN",
	"currency": "INR",
	"paymentMode": "LOCAL",
	"payoutType": "",
	"payoutMethod": "IMPS",
	"bizMode": "B",
	"accountNo": "61782371689519",
	"bankCode": "IN10000001",
	"registerCountry": "IN",
	"companyName": "test local ltd api.",
	"addressCountry": "IN",
	"addressProvince": "in province",
	"addressCity": "in city",
	"addressLine": "in address line test",
	"phoneNo": "0123456789",
	"phoneAreaCode": "1",
	"postCode": "12345678",
	"ifscCode": "abcd0111111",
	"relationProof": "invite/000959100493/260618155303900017.jpg",
	"callbackUrl": "www.baidu.com"
}

{
	"merOrderNo": "L0000011782377582405",
	"countryCode": "IN",
	"currency": "INR",
	"paymentMode": "LOCAL",
	"payoutType": "",
	"payoutMethod": "IMPS",
	"bizMode": "C",
	"accountNo": 1782377582414,
	"addressCountry": "IN",
	"addressProvince": "in province",
	"addressCity": "in city",
	"addressLine": "in address line test",
	"firstName": "xiao lin",
	"lastName": "liu",
	"phoneNo": "",
	"phoneAreaCode": "",
	"postCode": "12345678",
	"relationProof": "invite/000959100493/260618155303900017.jpg"
}

Response Body

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

string

required

Your original merchant order number, echoed back for correlation.

string

required

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

string

required

Beneficiary ID should be returned in real time; if missing, refer to SP2402.

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": "L0000011782371689504",
	"payeeId": "40596062515145300009",
	"bizFlowNo": "64596062515145300008",
	"status": "04"
}

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.

FileUpload

Transfer API

Market Specifics - Local Rails

Webhook Events

Beneficiary

Accounting

Meta Data API

Reference

Endpoint

Request Parameters

Request Example

Response Body

Response Example

​Endpoint

​Request Parameters

​Request Example

​Response Body

​Response Example

Endpoint

Request Parameters

Request Example

Response Body

Response Example