> ## 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.

# Register a Beneficiary

> Register a beneficiary for international remittance, FX settlement, withdrawal, or internal transfer. Submission is asynchronous — results are delivered via the sp3401 webhook.

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](/api/payees/beneficiary-inquiry). 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***).

<Expandable title="enterprise receiver fields">
  <ParamField body="merOrderNo" type="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.
  </ParamField>

  <ParamField body="countryCode" type="string" required>
    bank country code (e.g. `US`) ISO 3166-1 alpha-2.
  </ParamField>

  <ParamField body="currency" type="string" required>
    ISO 4217 3-letter currency code (e.g. `USD`). Omit this field to retrieve balances for all currencies.
  </ParamField>

  <ParamField body="paymentMode" type="string" required>
    paymentMode value is LOCAL or SWIFT.
  </ParamField>

  <ParamField body="payoutType" type="string">
    payoutType value is `WALLET, BANK`(Optional).
  </ParamField>

  <ParamField body="payoutMethod" type="string" required>
    payoutMethod value from List PayoutMethod API, when value SWIFT is `WIRE`.
  </ParamField>

  <ParamField body="bizMode" type="string" required>
    Business mode. Must be `B` for enterprise.
  </ParamField>

  <ParamField body="accountNo" type="string" required>
    Bank account number.
  </ParamField>

  <ParamField body="bankCode" type="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).
  </ParamField>

  <ParamField body="bankName" type="string">
    Bank name.
  </ParamField>

  <ParamField body="branchCode" type="string">
    Branch code.
  </ParamField>

  <ParamField body="proxyBankName" type="string">
    Correspondent bank name. Optional, `SWIFT` only. Either provide all three proxy bank fields or none.
  </ParamField>

  <ParamField body="proxyBankAddress" type="string">
    Correspondent bank address. Optional, `SWIFT` only.
  </ParamField>

  <ParamField body="proxyBankSwiftCode" type="string">
    Correspondent bank SWIFT code. Optional, `SWIFT` only.
  </ParamField>

  <ParamField body="swiftCode" type="string">
    SWIFT/BIC code of the receiver's bank. Required when `settlementNetwork` is `SWIFT`.
  </ParamField>

  <ParamField body="registerCountry" type="string" required>
    Country where the receiver's company is registered.
  </ParamField>

  <ParamField body="companyName" type="string" required>
    Company name.
  </ParamField>

  <ParamField body="localCompanyName" type="string">
    Local Company name.
  </ParamField>

  <ParamField body="emailNo" type="string">
    Company email address (optional).
  </ParamField>

  <ParamField body="phoneAreaCode" type="string">
    Phone area code. Required when `bankCountry` is `BR`, `KR`, `MA`, or `IN`. See the phone code dictionary.
  </ParamField>

  <ParamField body="phoneNo" type="string">
    Phone number (optional).
  </ParamField>

  <ParamField body="addressCountry" type="string" required>
    Country of business address. See the country dictionary.
  </ParamField>

  <ParamField body="addressProvince" type="string" required>
    State or province. Use the English name for non-CN countries. Use the province/city code for CN. See the dictionary.
  </ParamField>

  <ParamField body="addressCity" type="string" required>
    City.
  </ParamField>

  <ParamField body="addressLine" type="string" required>
    Street address.
  </ParamField>

  <ParamField body="postCode" type="string">
    Postal code (optional).
  </ParamField>

  <ParamField body="ifscCode" type="string">
    ifsc Code.
  </ParamField>

  <ParamField body="cnaps" type="string">
    cnaps.
  </ParamField>

  <ParamField body="taxIdNumber" type="string">
    tax id number.
  </ParamField>

  <ParamField body="businessLicenseImg" type="string">
    Business license image (optional). Applicable for CN.
  </ParamField>

  <ParamField body="registerCertImg" type="string">
    Business registration certificate image (optional). Applicable for HK.
  </ParamField>

  <ParamField body="incorporateCertImg" type="string">
    Certificate of incorporation image (optional). Applicable for non-CN and HK.
  </ParamField>

  <ParamField body="relationProof" type="array">
    **Conditionally required.** Business-relationship supporting materials (e.g., contracts, invoices). Maximum 3 files. Provide upload paths returned by the file upload endpoint.
  </ParamField>

  <ParamField body="callbackUrl" type="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.
  </ParamField>
</Expandable>

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

<Expandable title="individual receiver fields">
  <ParamField body="merOrderNo" type="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.
  </ParamField>

  <ParamField body="countryCode" type="string" required>
    bank country code (e.g. `US`) ISO 3166-1 alpha-2.
  </ParamField>

  <ParamField body="currency" type="string" required>
    ISO 4217 3-letter currency code (e.g. `USD`). Omit this field to retrieve balances for all currencies.
  </ParamField>

  <ParamField body="paymentMode" type="string" required>
    paymentMode value is LOCAL or SWIFT.
  </ParamField>

  <ParamField body="payoutType" type="string">
    payoutType value is `WALLET, BANK`(Optional).
  </ParamField>

  <ParamField body="payoutMethod" type="string" required>
    payoutMethod value from List PayoutMethod API, when value SWIFT is `WIRE`.
  </ParamField>

  <ParamField body="bizMode" type="string" required>
    Business mode. Must be `C` for individual.
  </ParamField>

  <ParamField body="accountNo" type="string" required>
    Bank account number.
  </ParamField>

  <ParamField body="bankCode" type="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).
  </ParamField>

  <ParamField body="bankName" type="string">
    Bank name.
  </ParamField>

  <ParamField body="branchCode" type="string">
    Branch code.
  </ParamField>

  <ParamField body="proxyBankName" type="string">
    Correspondent bank name. Optional, `SWIFT` only. Either provide all three proxy bank fields or none.
  </ParamField>

  <ParamField body="proxyBankAddress" type="string">
    Correspondent bank address. Optional, `SWIFT` only.
  </ParamField>

  <ParamField body="proxyBankSwiftCode" type="string">
    Correspondent bank SWIFT code. Optional, `SWIFT` only.
  </ParamField>

  <ParamField body="swiftCode" type="string">
    SWIFT/BIC code of the receiver's bank. Required when `settlementNetwork` is `SWIFT`.
  </ParamField>

  <ParamField body="idType" type="string" required>
    ID document type. `01` = National ID card, `02` = Passport.
  </ParamField>

  <ParamField body="idNumber" type="string" required>
    ID document number.
  </ParamField>

  <ParamField body="firstName" type="string" required>
    English first name.
  </ParamField>

  <ParamField body="lastName" type="string" required>
    English last name.
  </ParamField>

  <ParamField body="birthDate" type="string" required>
    Date of birth. Format: `YYYY-MM-DD`.
  </ParamField>

  <ParamField body="placeOfBirth" type="string" required>
    Place of birth. See the country dictionary.
  </ParamField>

  <ParamField body="nationality" type="string" required>
    Nationality. See the country dictionary.
  </ParamField>

  <ParamField body="gender" type="string" required>
    Gender. `M` = Male, `F` = Female, `X` = Other.
  </ParamField>

  <ParamField body="emailNo" type="string">
    Email address (optional).
  </ParamField>

  <ParamField body="phoneAreaCode" type="string">
    Phone area code. Required when `bankCountry` is `BR`, `KR`, `MA`, or `IN`. See the phone code dictionary.
  </ParamField>

  <ParamField body="phoneNo" type="string">
    Phone number (optional).
  </ParamField>

  <ParamField body="addressCountry" type="string" required>
    Country of residence. See the country dictionary.
  </ParamField>

  <ParamField body="addressProvince" type="string" required>
    State or province. Use the English name for non-CN countries. Use the province/city code for CN. See the dictionary.
  </ParamField>

  <ParamField body="addressCity" type="string" required>
    City.
  </ParamField>

  <ParamField body="addressLine" type="string" required>
    Street address. Allowed characters: `^[a-zA-Z0-9\s.,!?:;'"()\[\]{}/*\\-]+$`
  </ParamField>

  <ParamField body="postCode" type="string">
    Postal code (optional).
  </ParamField>

  <ParamField body="ifscCode" type="string">
    ifsc Code.
  </ParamField>

  <ParamField body="cnaps" type="string">
    cnaps.
  </ParamField>

  <ParamField body="taxIdNumber" type="string">
    tax id number.
  </ParamField>

  <ParamField body="frontCertImg" type="string">
    National emblem side of the ID card, or passport photo page.
  </ParamField>

  <ParamField body="backCertImg" type="string">
    Portrait side of the ID card. Required when `idType` is `01`.
  </ParamField>

  <ParamField body="relationProof" type="array">
    **Conditionally required.** Business-relationship supporting materials (e.g., contracts, invoices). Maximum 3 files. Provide upload paths returned by the file upload endpoint.
  </ParamField>

  <ParamField body="callbackUrl" type="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.
  </ParamField>
</Expandable>

## Request Example

<CodeGroup>
  ```json Company IN-IMPS theme={null}
  {
  	"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"
  }
  ```

  ```json Individual IN-IMPS theme={null}
  {
  	"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"
  }
  ```
</CodeGroup>

## Response Body

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

<ResponseField name="merOrderNo" type="string" required>
  Your original merchant order number, echoed back for correlation.
</ResponseField>

<ResponseField name="bizFlowNo" type="string" required>
  Gcashier Pay's internal flow reference number for this registration. Retain this value — you will need it to query status via sp2402.
</ResponseField>

<ResponseField name="payeeId" type="string" required>
  Beneficiary ID should be returned in real time; if missing, refer to SP2402.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current registration status at the time of submission. Possible values:

  | Value | Description       |
  | ----- | ----------------- |
  | `01`  | Under Review      |
  | `03`  | Rejected          |
  | `04`  | Normal (Approved) |
</ResponseField>

## Response Example

```json theme={null}
{
	"merOrderNo": "L0000011782371689504",
	"payeeId": "40596062515145300009",
	"bizFlowNo": "64596062515145300008",
	"status": "04"
}
```

<Note>
  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.
</Note>