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

# sp1101 Agent Merchant Access Application

> POST /api/sp1101 — submit merchant KYC information to Gcashier Pay to initiate an onboarding review for agent merchants.

To onboard a new agent merchant, you submit their KYC data to Gcashier Pay via this endpoint. Gcashier Pay validates the payload in real time and responds with an `ACCEPT` status once the submission is received. The final approval or rejection is then delivered asynchronously to the `callbackUrl` you provide, through the [sp3101 webhook](/api/merchant/access-notification).

<Note>
  This API uses a **two-phase response model**. The synchronous response only confirms receipt (`ACCEPT`). The definitive review outcome — including your assigned `merchantNo` and `token` — arrives via the **sp3101 notification webhook**. Make sure your `callbackUrl` is publicly reachable before submitting.
</Note>

## Endpoint

```
POST https://{baseUrl}/api/sp1101
```

| Attribute        | Value                                                     |
| ---------------- | --------------------------------------------------------- |
| Transaction Code | `sp1101`                                                  |
| Invocation Mode  | Real-time (synchronous `ACCEPT`; final result via sp3101) |

***

## Request Parameters

### Top-Level Fields

<ParamField body="merOrderNo" type="string(32)" optional>
  Your unique order reference for this application. You can use this to correlate the sp3101 callback with your internal records. **O**
</ParamField>

<ParamField body="email" type="string(255)" required>
  Contact email address for the merchant. Used for review notifications when `noticeMarker` is `1`. **M**
</ParamField>

<ParamField body="phoneAreaCode" type="string(10)" required>
  International dialling code for the merchant's phone number, e.g. `852` for Hong Kong. **M**
</ParamField>

<ParamField body="phoneNum" type="string(32)" required>
  Merchant contact phone number, without the area code. **M**
</ParamField>

<ParamField body="referralChannel" type="string(16)" required>
  Referral agent number assigned to you by Gcashier Pay. Required for all agent-submitted applications. **M**
</ParamField>

<ParamField body="countryCode" type="string(2)" required>
  ISO 3166-1 alpha-2 country code for the merchant's registered jurisdiction, e.g. `HK`, `US`, `CN`. **M**
</ParamField>

<ParamField body="merNameEn" type="string(255)" required>
  Merchant's legal English company name, exactly as it appears on the business registration certificate. **M**
</ParamField>

<ParamField body="merNameCn" type="string(255)" optional>
  Merchant's Chinese company name. Required when `countryCode` is `CN`. **O**
</ParamField>

<ParamField body="payerCity" type="string(128)" required>
  City where the merchant's principal office is located. **M**
</ParamField>

<ParamField body="realCompanyAddress" type="string(255)" required>
  Full physical address of the merchant's registered office. **M**
</ParamField>

<ParamField body="addressType" type="string(1)" required>
  Type of office premises. **M**

  | Value | Description                      |
  | ----- | -------------------------------- |
  | `0`   | Self-Rented Office               |
  | `1`   | Secretariat Address              |
  | `2`   | Shared Office / Co-working Space |
</ParamField>

<ParamField body="certificateNo" type="string(18)" required>
  Business registration or company license number. **M**
</ParamField>

<ParamField body="certificate" type="List<String>" required>
  SFTP file paths to the merchant's business registration documents uploaded via the Gcashier Pay file upload service, e.g. `["uploadFile/reg_cert.png"]`. **M**
</ParamField>

<ParamField body="companyWebsite" type="string(255)" optional>
  Merchant's corporate website URL. **O**
</ParamField>

<ParamField body="webSiteOrApp" type="string(255)" optional>
  Trading website or mobile app URL used by end-customers. Required when `businessNature.natureType` is `2` (E-commerce). **O**
</ParamField>

<ParamField body="clientCountry" type="List<String>" required>
  ISO alpha-2 codes of the countries where the merchant's main customers are located, e.g. `["US", "GB"]`. **M**
</ParamField>

<ParamField body="businessMainActors" type="string(1)" required>
  Indicates whether the business is primarily operated by a company or individuals. **M**

  | Value | Description |
  | ----- | ----------- |
  | `0`   | Company     |
  | `1`   | Individual  |
</ParamField>

<ParamField body="lastYearTurnover" type="string(1)" required>
  Previous year's annual turnover range in USD. **M**

  | Value | Range                        |
  | ----- | ---------------------------- |
  | `0`   | Less than USD 100,000        |
  | `1`   | USD 100,000 – 1,000,000      |
  | `2`   | USD 1,000,000 – 10,000,000   |
  | `3`   | USD 10,000,000 – 100,000,000 |
  | `4`   | More than USD 100,000,000    |
  | `5`   | N/A (new company)            |
</ParamField>

<ParamField body="estimatedTradingVolume" type="string(1)" required>
  Expected monthly transaction volume in USD. **M**

  | Value | Range                     |
  | ----- | ------------------------- |
  | `0`   | Less than USD 50,000      |
  | `1`   | USD 50,000 – 100,000      |
  | `2`   | USD 100,000 – 500,000     |
  | `3`   | USD 500,000 – 1,000,000   |
  | `4`   | USD 1,000,000 – 5,000,000 |
  | `5`   | More than USD 5,000,000   |
</ParamField>

<ParamField body="sourceFunds" type="List<String>" required>
  Codes indicating the source of the merchant's operating funds. Refer to the Enums appendix for valid values, e.g. `["03"]`. **M**
</ParamField>

<ParamField body="paymentPurpose" type="List<String>" required>
  Codes describing the purpose of payments. Refer to the Enums appendix for valid values, e.g. `["26"]`. **M**
</ParamField>

<ParamField body="riskCountryTransaction" type="string(2)" required>
  Whether the merchant conducts business with sanctioned jurisdictions (Iran, DPRK, Cuba). **M**

  | Value | Description |
  | ----- | ----------- |
  | `0`   | No          |
  | `1`   | Yes         |
</ParamField>

<ParamField body="customerIdentity" type="List<String>" required>
  Codes representing the type of identity documents held by the merchant's customers. Refer to the Enums appendix for valid values. **M**
</ParamField>

<ParamField body="customerId" type="List<personInfo>" required>
  Identity documents for the merchant's authorised representative(s). See the **personInfo** schema below. **M**
</ParamField>

<ParamField body="shareholder" type="List<personInfo>" required>
  Identity documents for all beneficial owners holding more than 25% of shares. See the **personInfo** schema below. **M**
</ParamField>

<ParamField body="director" type="List<personInfo>">
  Identity documents for company directors. **C** — Required for merchants registered outside mainland China.
</ParamField>

<ParamField body="legalPerson" type="List<personInfo>">
  Identity documents for the legal representative. **C** — Required when `countryCode` is `CN`.
</ParamField>

<ParamField body="authorization" type="List<String>" required>
  SFTP paths to the board resolution or power-of-attorney documents authorising the application, e.g. `["uploadFile/board_resolution.pdf"]`. **M**
</ParamField>

<ParamField body="parentRemark" type="string(2)" required>
  Whether the merchant has a parent company. `0` = No, `1` = Yes. **M**
</ParamField>

<ParamField body="branchRemark" type="string(2)" required>
  Whether the merchant has subsidiaries or branch offices. `0` = No, `1` = Yes. **M**
</ParamField>

<ParamField body="noticeMarker" type="string(1)" required>
  Controls whether Gcashier Pay sends review status notifications to the merchant by email and SMS. `0` = Do not notify, `1` = Notify. **M**
</ParamField>

<ParamField body="callbackUrl" type="string(255)" required>
  Your publicly accessible HTTPS endpoint that will receive the sp3101 webhook once the review is complete. **M**
</ParamField>

<ParamField body="processVersion" type="string(10)" optional>
  Process version identifier. Supply this when resubmitting an application after receiving a process ID of V2 or later. **O**
</ParamField>

***

### `businessNature` Object

<ParamField body="businessNature" type="object" required>
  Describes the merchant's primary line of business. **M**

  <Expandable title="businessNature fields">
    <ParamField body="natureType" type="string(2)" required>
      High-level business category. **M**

      | Value | Description    |
      | ----- | -------------- |
      | `0`   | Goods Trade    |
      | `1`   | Services Trade |
      | `2`   | E-commerce     |
    </ParamField>

    <ParamField body="natures" type="List<String>" required>
      One or more business nature detail codes from the Enums appendix, e.g. `["45", "14"]`. **M**
    </ParamField>
  </Expandable>
</ParamField>

***

### `personInfo` Object

The following schema applies to the `customerId`, `shareholder`, `director`, and `legalPerson` arrays.

<ParamField body="type" type="string(2)" required>
  Document type. `0` = National ID Card, `1` = Passport. **M**
</ParamField>

<ParamField body="issuPlace" type="string(2)" required>
  ISO alpha-2 code of the country that issued the document, e.g. `HK`. **M**
</ParamField>

<ParamField body="certName" type="string(64)" required>
  Full name exactly as it appears on the identity document. **M**
</ParamField>

<ParamField body="certNo" type="string(32)" required>
  Document number (passport number or ID card number). **M**
</ParamField>

<ParamField body="certificates" type="List<String>" required>
  SFTP paths to scanned images of the identity document. For ID cards, supply `[front_image, back_image]`. **M**
</ParamField>

<ParamField body="dateOfBirth" type="string(10)" optional>
  Date of birth in `yyyy-MM-dd` format. **O**
</ParamField>

<ParamField body="certValidEndDate" type="string(10)" optional>
  Document expiry date in `yyyy-MM-dd` format. Use `9999-12-31` for documents with no expiry. **O**
</ParamField>

<ParamField body="currentCountry" type="string(2)" required>
  ISO alpha-2 code of the person's current country of residence. **M**
</ParamField>

<ParamField body="currentAddress" type="string(255)" required>
  Full current residential address of the person. **M**
</ParamField>

***

## Request Example

```json theme={null}
{
  "merOrderNo": "311516477399200",
  "referralChannel": "0103100001",
  "realCompanyAddress": "123 Main Street, Kowloon",
  "businessMainActors": "0",
  "lastYearTurnover": "2",
  "estimatedTradingVolume": "2",
  "certificateNo": "HK334333333",
  "addressType": "0",
  "companyWebsite": "https://www.example.com",
  "clientCountry": ["US", "GB"],
  "webSiteOrApp": "mystore.com",
  "businessNature": {
    "natureType": "2",
    "natures": ["45", "14"]
  },
  "noticeMarker": "1",
  "callbackUrl": "https://yourplatform.com/callback/merchant",
  "sourceFunds": ["03"],
  "paymentPurpose": ["26"],
  "riskCountryTransaction": "0",
  "branchRemark": "0",
  "parentRemark": "0",
  "certificate": ["uploadFile/reg_cert.png"],
  "customerIdentity": ["0"],
  "customerId": [
    {
      "type": "1",
      "issuPlace": "HK",
      "certName": "John Smith",
      "certNo": "A12345678",
      "certificates": ["uploadFile/passport_front.png"],
      "currentCountry": "HK",
      "currentAddress": "123 Main Street, Kowloon, HK"
    }
  ],
  "shareholder": [
    {
      "type": "1",
      "issuPlace": "HK",
      "certName": "Jane Doe",
      "certNo": "B98765432",
      "certificates": ["uploadFile/passport_front2.png"],
      "currentCountry": "HK",
      "currentAddress": "456 Queen Road, Central, HK"
    }
  ],
  "authorization": ["uploadFile/board_resolution.pdf"],
  "countryCode": "HK",
  "merNameEn": "Example Trading Limited",
  "email": "admin@example.com",
  "phoneAreaCode": "852",
  "phoneNum": "98765432",
  "payerCity": "Hong Kong"
}
```

***

## Response Body

<ResponseField name="bizFlow" type="string(32)" required>
  Gcashier Pay's internal business order number for this application. Store this value — you will need it to track the review and to submit any modifications via sp1102. **M**
</ResponseField>

<ResponseField name="merOrderNo" type="string(32)" optional>
  Echo of the `merOrderNo` you submitted in the request, if provided. **O**
</ResponseField>

<ResponseField name="status" type="string(6)" required>
  Synchronous processing status. Always `ACCEPT` for a successful submission, indicating the payload passed validation and has been queued for review. **M**
</ResponseField>

<ResponseField name="code" type="string(6)" required>
  Result code. `S00001` means the application was received and is awaiting manual review. **M**
</ResponseField>

<ResponseField name="message" type="string(255)" required>
  Human-readable description of the result, e.g. `"ACCEPT"`. **M**
</ResponseField>

## Response Example

```json theme={null}
{
  "bizFlow": "210622162803810002",
  "merOrderNo": "311516477399200",
  "status": "ACCEPT",
  "code": "S00001",
  "message": "ACCEPT"
}
```

***

## Notes

<Note>
  The `ACCEPT` status in the synchronous response only confirms that Gcashier Pay has **received and validated** your submission. The actual approval decision is delivered asynchronously via the **sp3101 webhook** posted to your `callbackUrl`. Do not treat `ACCEPT` as final approval.
</Note>

<Tip>
  Before going live, verify that your `callbackUrl` returns an HTTP `200` response to POST requests. Gcashier Pay will retry failed webhook deliveries, but delays in receipt can slow down your merchant's onboarding.
</Tip>

<Warning>
  All file paths in `certificate`, `authorization`, and `certificates` fields inside `personInfo` must be valid SFTP paths obtained from the Gcashier Pay file upload service. Submitting local file names or external URLs will cause the application to be rejected.
</Warning>