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

# Complete Merchant Onboarding with Gcashier Pay API

> Submit your KYC application, receive your merchant token via webhook, and go live with Gcashier Pay in a few straightforward API calls.

Merchant onboarding with Gcashier Pay is a fully API-driven KYC process. You submit your business details and supporting documents through the **sp1101** endpoint, Gcashier Pay's compliance team reviews the application, and the result — including your live merchant token — is delivered to your server via the **sp3101** webhook. If your application requires supplementary materials, you'll receive a `80000` callback code prompting you to upload them. Once approved, you can modify your registration at any time using **sp1102**.

## Overview

<Steps>
  <Step title="Submit merchant access application (sp1101)">
    Send your KYC details, business information, and document URLs.
  </Step>

  <Step title="Receive the onboarding result (sp3101 webhook)">
    Gcashier Pay posts the review outcome — and your token — to your callback URL.
  </Step>

  <Step title="Handle additional material requests (code 80000)">
    If compliance needs more documents, re-submit via the `reMaterial` field.
  </Step>

  <Step title="Modify your application if needed (sp1102)">
    Update any registered fields before or after approval.
  </Step>
</Steps>

***

## Step 1 — Submit the Merchant Access Application

Call **POST /api/sp1101** with your business profile, document URLs, and callback endpoint. The table below describes the key request fields.

| Field                        | Required | Description                                                     |
| ---------------------------- | -------- | --------------------------------------------------------------- |
| `merOrderNo`                 | M        | Your unique order reference for this application                |
| `email`                      | M        | Business contact email                                          |
| `phoneAreaCode` / `phoneNum` | M        | Contact phone with country prefix                               |
| `countryCode`                | M        | ISO country code of the business                                |
| `merNameEn`                  | M        | Merchant name in English                                        |
| `merNameCn`                  | O        | Merchant name in Chinese (optional)                             |
| `parentRemark`               | M        | Whether this is a sub-merchant: `0` = No, `1` = Yes             |
| `addressType`                | M        | `0` = Self-Rented, `1` = Secretariat, `2` = Shared              |
| `businessMainActors`         | M        | `0` = Company, `1` = Individual                                 |
| `lastYearTurnover`           | M        | Turnover band 0–5                                               |
| `estimatedTradingVolume`     | M        | Estimated volume band 0–5                                       |
| `riskCountryTransaction`     | M        | Whether the merchant transacts with risk-listed countries       |
| `certificate`                | M        | `List<String>` of business certificate document URLs            |
| `customerIdentity`           | M        | `List<String>` of identity document URLs                        |
| `customerId`                 | M        | `List<personInfo>` — customer identity detail objects           |
| `shareholder`                | M        | `List<personInfo>` — shareholder identity detail objects        |
| `authorization`              | M        | `List<String>` of authorization document URLs                   |
| `sourceFunds`                | M        | `List<String>` of fund source evidence URLs                     |
| `paymentPurpose`             | M        | `List<String>` of payment purpose document URLs                 |
| `clientCountry`              | M        | `List<String>` of countries where clients are based             |
| `businessNature`             | M        | Object with `natureType` and `natures` describing your business |
| `callbackUrl`                | M        | Your HTTPS endpoint for the sp3101 webhook                      |
| `noticeMarker`               | M        | Notification preference marker                                  |
| `certificateNo`              | M        | Business registration / certificate number                      |
| `processVersion`             | O        | Process version identifier (leave blank for default)            |

<Note>
  All document fields accept HTTPS URLs pointing to pre-uploaded files. Ensure each URL is publicly accessible by Gcashier Pay's servers at review time. Files must be in PDF, JPG, or PNG format and must not exceed 10 MB each.
</Note>

### Request Example

<CodeGroup>
  ```json sp1101 Request theme={null}
  {
    "merOrderNo": "MER20240601001",
    "email": "compliance@acme-trade.com",
    "phoneAreaCode": "65",
    "phoneNum": "81234567",
    "referralChannel": "PARTNER_PORTAL",
    "countryCode": "SG",
    "merNameEn": "Acme Trade Pte Ltd",
    "merNameCn": "艾克米贸易有限公司",
    "payerCity": "Singapore",
    "parentRemark": "0",
    "branchRemark": "HQ",
    "addressType": "0",
    "realCompanyAddress": "80 Robinson Road, #08-01, Singapore 068898",
    "businessMainActors": "0",
    "lastYearTurnover": "3",
    "estimatedTradingVolume": "2",
    "riskCountryTransaction": "N",
    "certificateNo": "202400123G",
    "noticeMarker": "1",
    "certificate": [
      "https://docs.acme-trade.com/kyc/bizreg.pdf"
    ],
    "customerIdentity": [
      "https://docs.acme-trade.com/kyc/id_front.jpg",
      "https://docs.acme-trade.com/kyc/id_back.jpg"
    ],
    "customerId": [
      {
        "name": "Jane Doe",
        "idType": "PASSPORT",
        "idNo": "E12345678",
        "nationality": "SG"
      }
    ],
    "shareholder": [
      {
        "name": "John Smith",
        "idType": "PASSPORT",
        "idNo": "A98765432",
        "nationality": "GB",
        "shareholdingRatio": "60"
      }
    ],
    "authorization": [
      "https://docs.acme-trade.com/kyc/authorization_letter.pdf"
    ],
    "sourceFunds": [
      "https://docs.acme-trade.com/kyc/bank_statement_q1.pdf"
    ],
    "paymentPurpose": [
      "https://docs.acme-trade.com/kyc/payment_purpose.pdf"
    ],
    "clientCountry": ["SG", "MY", "ID"],
    "businessNature": {
      "natureType": "ECOMMERCE",
      "natures": ["Retail", "Cross-border goods"]
    },
    "callbackUrl": "https://api.acme-trade.com/webhooks/gcashier/onboarding"
  }
  ```

  ```json sp1101 Response theme={null}
  {
    "bizFlow": "BF20240601000123",
    "merOrderNo": "MER20240601001",
    "status": "ACCEPT",
    "code": "S00001",
    "message": "Application received and under review."
  }
  ```
</CodeGroup>

A `status` of `ACCEPT` and `code` of `S00001` means Gcashier Pay has accepted your submission for review. Store `bizFlow` — you'll need it to track progress and for any subsequent modification requests.

***

## Step 2 — Receive the Onboarding Result Webhook (sp3101)

When the compliance review is complete, Gcashier Pay posts a JSON payload to the `callbackUrl` you specified. On success, the payload includes your permanent **`token`**, which you must include in the `Authorization` header of all subsequent API calls.

### Webhook Payload

<CodeGroup>
  ```json sp3101 Webhook — Approved theme={null}
  {
    "bizFlow": "BF20240601000123",
    "merOrderNo": "MER20240601001",
    "code": "S00000",
    "message": "Merchant access approved.",
    "merchantNo": "MCH0000456",
    "merNameEn": "Acme Trade Pte Ltd",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudE5vIjoiTUNIMDAwMDQ1NiJ9.signature"
  }
  ```

  ```json sp3101 Webhook — Rejected theme={null}
  {
    "bizFlow": "BF20240601000123",
    "merOrderNo": "MER20240601001",
    "code": "S00002",
    "message": "Application rejected: insufficient identity documentation.",
    "merchantNo": "",
    "merNameEn": "Acme Trade Pte Ltd",
    "token": ""
  }
  ```
</CodeGroup>

<Warning>
  Store your `token` securely — treat it like an API secret key. Rotate it immediately if you suspect it has been compromised by contacting Gcashier Pay support.
</Warning>

| Code     | Meaning                                                |
| -------- | ------------------------------------------------------ |
| `S00000` | Application approved; `token` is populated             |
| `S00002` | Application rejected; review the `message` for reasons |
| `80000`  | Additional materials required (see below)              |

***

## Step 3 — Handle Additional Material Requests (Code 80000)

If the webhook delivers `code: "80000"`, compliance has reviewed your application but requires supplementary documentation before approval. The response body will include a `reMaterial` field listing the specific document types needed.

<Note>
  When you receive a `80000` callback, your `bizFlow` remains active. You do not need to submit a new sp1101 request — instead, call **sp1102** with the same `bizFlow` and attach the requested materials.
</Note>

**How to respond:**

1. Inspect the `reMaterial` array to identify which document categories are required.
2. Upload the new files and obtain fresh HTTPS URLs.
3. Call **POST /api/sp1102** with your `bizFlow` and the updated document fields (see Step 4).

***

## Step 4 — Modify Merchant Access (sp1102)

Use **POST /api/sp1102** to update your application at any stage — whether responding to a `80000` request or correcting details after approval.

<CodeGroup>
  ```json sp1102 Request — Respond to Additional Materials Request theme={null}
  {
    "bizFlow": "BF20240601000123",
    "sourceFunds": [
      "https://docs.acme-trade.com/kyc/bank_statement_q2.pdf",
      "https://docs.acme-trade.com/kyc/audited_accounts_2023.pdf"
    ],
    "paymentPurpose": [
      "https://docs.acme-trade.com/kyc/updated_payment_purpose.pdf"
    ]
  }
  ```

  ```json sp1102 Response theme={null}
  {
    "bizFlow": "BF20240601000123",
    "status": "ACCEPT",
    "code": "S00001",
    "message": "Modification received and under review."
  }
  ```
</CodeGroup>

Only include the fields you need to change in the sp1102 request body. All other registered fields remain unchanged.

***

## Test Environment Behaviour

In the Gcashier Pay sandbox, you can simulate different review outcomes by controlling the **last digit** of your `merOrderNo`:

| Last digit of `merOrderNo` | Simulated outcome                                          |
| -------------------------- | ---------------------------------------------------------- |
| `0` – `3`                  | Approved — `S00000` webhook delivered with test token      |
| `4` – `6`                  | Rejected — `S00002` webhook delivered                      |
| `7` – `9`                  | Additional materials requested — `80000` webhook delivered |

<Tip>
  Start sandbox testing with a `merOrderNo` ending in `1` to get an instant approval and a test token you can use for all downstream API calls.
</Tip>