> For the complete documentation index, see [llms.txt](https://docs.pagsmile.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagsmile.com/reference/remittance-api/business/onboarding/create-corporate-merchant.md).

# Create Corporate Merchant

Onboards a corporate merchant by submitting its contact, business, director, and ultimate beneficial owner (UBO) information.

{% hint style="info" %}
After a successful request, store the returned `merchant_id`. You will need it to query or update the corporate merchant later.
{% endhint %}

**Endpoint**

`POST /remittance/merchant/create-corporation`

**Sandbox base URL:** `https://rem-api-sandbox.pagsmile.com`\
**Content-Type:** `application/json; charset=UTF-8`

The request uses the standard [Remittance API request envelope](https://docs.pagsmile.com/remittance-api/common). The tables below describe the decrypted `biz_data` object.

{% hint style="info" %}
**Requirement:** `M` = Mandatory, `O` = Optional, and `C` = Conditional. A conditional field is mandatory only when the condition stated in its description applies.
{% endhint %}

{% hint style="warning" %}
Submit all required fields. Encrypt `biz_data`, encrypt the AES key into `random_key`, and sign the request according to the Common request specification.
{% endhint %}

### Business payload before encryption

The following tables define the complete plaintext JSON object that must be AES-encrypted before it is assigned to the request envelope's `biz_data` field.

#### Business payload

<table><thead><tr><th width="155.6015625">Field</th><th width="119.91015625">Type</th><th width="117.296875">Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>request_no</code></td><td>string</td><td>O</td><td><p>Merchant request number used as the idempotency key for corporate merchant creation.</p><p>Length: 16–36 characters.</p></td></tr><tr><td><code>mobile</code></td><td>string(16)</td><td>O</td><td>Mobile phone number of the merchant or primary contact.<br>Format: International number including the country calling code.</td></tr><tr><td><code>email</code></td><td>string(80)</td><td>M</td><td>Email address of the merchant or primary contact.<br>Format: Valid email address.</td></tr><tr><td><code>business_scenes</code></td><td>list&#x3C;Integer></td><td>M</td><td>List of integer codes identifying the merchant's business scenes.<br>Format: <code>List&#x3C;Integer></code>; submit one or more keys listed in <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/business-scenes">Business Scenes</a>.<br>Example: <code>[1005]</code>.</td></tr><tr><td><code>website_url</code></td><td>string(128)</td><td>O</td><td>Publicly accessible URL of the merchant's official website.<br>Format: URL; maximum 128 characters.</td></tr></tbody></table>

#### Corporation object

<table><thead><tr><th width="298.359375">Field</th><th width="142.5703125">Type</th><th width="120.5390625">Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>corporation.registration_name</code></td><td>string(256)</td><td>M</td><td>Legal name exactly as shown on the official registration documents.<br>Supports UTF-8/Unicode characters.<br>No character-set restriction.<br>Maximum 256 bytes.</td></tr><tr><td><code>corporation.name_en</code></td><td>string(128)</td><td>M</td><td>English name used for bank account applications.<br>Format: <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">COMPANY_NAME_EN</a>; <code>^[A-Za-z0-9][A-Za-z0-9 .,&#x26;'()"/-]*$</code>.<br>The first character must be an English letter or digit.<br>Maximum 128 bytes.</td></tr><tr><td><code>corporation.industry_category</code></td><td>string</td><td>M</td><td>Industry category of the corporation's primary business activity.<br>Format: String; submit one of the values listed in <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/industry-category">Industry Category</a>.</td></tr><tr><td><code>corporation.registration_code</code></td><td>string(32)</td><td>M</td><td>Official registration number issued to the corporation by the relevant registration authority.<br>Maximum length: 32 bytes.</td></tr><tr><td><code>corporation.registration_country</code></td><td>string(2)</td><td>M</td><td>Country in which the corporation is legally registered.<br>Format: Two-letter ISO 3166-1 alpha-2 country code.<br>See <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/country-code">Country Code</a> for supported values.</td></tr><tr><td><code>corporation.registration_date</code></td><td>string</td><td>O</td><td>Date on which the corporation was legally established.<br>Format: <code>YYYY-MM-DD</code>.</td></tr></tbody></table>

**Registered address object**

<table><thead><tr><th width="295.359375">Field</th><th width="142.40625">Type</th><th width="116.5078125">Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>corporation.registration_address.line1</code></td><td>string(5–128)</td><td>C</td><td>Primary address line of the corporation's registered office, including the street name and building number.<br>Required when <code>full_address</code> is omitted.</td></tr><tr><td><code>corporation.registration_address.line2</code></td><td>string(5–128)</td><td>O</td><td>Additional registered-address information, such as the unit, suite, floor, or building name.<br>Optional, including when full_address is omitted.</td></tr><tr><td><code>corporation.registration_address.postal_code</code></td><td>string(4–16)</td><td>O</td><td>ZIP or postal code of the corporation's registered office.<br>Maximum length: 16 bytes.<br>Optional, including when full_address is omitted.</td></tr><tr><td><code>corporation.registration_address.city_name</code></td><td>string(50)</td><td>C</td><td>City in which the corporation's registered office is located.<br>Required when <code>full_address</code> is omitted.</td></tr><tr><td><code>corporation.registration_address.state</code></td><td>string(50)</td><td>O</td><td>State, province, or administrative region of the corporation's registered office.<br>Maximum length: 50 bytes.<br>Optional, including when full_address is omitted.</td></tr><tr><td><code>corporation.registration_address.country_code</code></td><td>string(2)</td><td>O</td><td>Country of the corporation's registered-office address.<br>Format: Two-letter ISO 3166-1 alpha-2 country code.<br>See <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/country-code">Country Code</a> for supported values.<br>Optional, including when full_address is omitted.</td></tr><tr><td><code>corporation.registration_address.full_address</code></td><td>string(256)</td><td>C</td><td>Complete address as a single string. Maximum length: 256. Required when line1 and city_name are not used. When full_address is provided, line1 and city_name may be omitted. The structured fields line2, postal_code, and state are optional.</td></tr></tbody></table>

#### Director object

<table><thead><tr><th width="198.7578125">Field</th><th width="143.61328125">Type</th><th width="123.0625">Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>director.first_name</code></td><td>string(2–64)</td><td>C</td><td>Director's legal given name in English or Pinyin, corresponding to the name on the identity document used for verification.<br>Format: <code>^[a-zA-Z-,./ ]+$</code>.<br>Length: 2–64 characters.<br>Required together with <code>last_name</code> when <code>local_name</code> is omitted.</td></tr><tr><td><code>director.last_name</code></td><td>string(2–64)</td><td>C</td><td>Director's legal family name in English or Pinyin, corresponding to the name on the identity document used for verification.<br>Format: <code>^[a-zA-Z-,./ ]+$</code>.<br>Length: 2–64 characters.<br>Required together with <code>first_name</code> when <code>local_name</code> is omitted.</td></tr><tr><td><code>director.local_name</code></td><td>string(128)</td><td>C</td><td>Director's full legal name in the local language, exactly as shown on the identity document used for verification.<br>Supports UTF-8/Unicode characters.<br>No character-set restriction.<br>Maximum 128 bytes.<br>Required when <code>first_name</code> and <code>last_name</code> are not both provided. Alternatively, provide both <code>first_name</code> and <code>last_name</code>.</td></tr><tr><td><code>director.id_type</code></td><td>integer</td><td>M</td><td>Type of identity document submitted for the director.<br>Format: Integer code.<br>See <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/id-type">ID Type</a> for supported values.</td></tr><tr><td><code>director.id_no</code></td><td>string(6–20)</td><td>M</td><td>Director's identity document number, entered exactly as shown on the document.<br>Length: 6–18 characters.</td></tr><tr><td><code>director.nationality</code></td><td>string(2)</td><td>M</td><td>Country representing the director's nationality.<br>Format: Two-letter ISO 3166-1 alpha-2 country code.<br>See <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/country-code">Country Code</a> for supported values.</td></tr><tr><td><code>director.date_birth</code></td><td>string</td><td>M</td><td>Director's date of birth.<br>Format: <code>yyyy-MM-dd</code>.</td></tr></tbody></table>

**Director address object**

<table><thead><tr><th>Field</th><th width="153.4765625">Type</th><th width="123.78515625">Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>director.address.line1</code></td><td>string(5–128)</td><td>C</td><td>Primary address line of the director's current residence, including the street name and building number.<br>Length: 5–128 bytes.<br>Required when <code>full_address</code> is omitted.</td></tr><tr><td><code>director.address.line2</code></td><td>string(5–128)</td><td>O</td><td>Additional residential-address information for the director, such as the unit, apartment, floor, or building name.<br>When provided, 5–128 bytes.<br>Optional, including when full_address is omitted.</td></tr><tr><td><code>director.address.postal_code</code></td><td>string(4–16)</td><td>O</td><td>ZIP or postal code of the director's residential address.<br>Maximum length: 16 bytes.<br>Optional, including when full_address is omitted.</td></tr><tr><td><code>director.address.city_name</code></td><td>string(50)</td><td>C</td><td>City in which the director currently resides.<br>Maximum length: 50 bytes.<br>Required when <code>full_address</code> is omitted.</td></tr><tr><td><code>director.address.state</code></td><td>string(50)</td><td>O</td><td>State, province, or administrative region of the director's residential address.<br>Maximum length: 50 bytes.<br>Optional, including when full_address is omitted.</td></tr><tr><td><code>director.address.country_code</code></td><td>string(2)</td><td>O</td><td>Country of the director's residential address.<br>Format: Two-letter ISO 3166-1 alpha-2 country code.<br>See <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/country-code">Country Code</a> for supported values.<br>Optional, including when full_address is omitted.</td></tr><tr><td><code>director.address.full_address</code></td><td>string(256)</td><td>C</td><td>Complete address as a single string. Maximum length: 256. Required when line1 and city_name are not used. When full_address is provided, line1 and city_name may be omitted. The structured fields line2, postal_code, and state are optional.</td></tr></tbody></table>

#### Shareholders

`shareholders` is an array. Submit one Shareholder object for each UBO or shareholder.

**Shareholder object**

Each item in `shareholders` contains the following fields.

<table><thead><tr><th>Field</th><th width="127.3046875">Type</th><th width="130.73046875">Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>shareholders[].first_name</code></td><td>string(50)</td><td>C</td><td>Shareholder's legal given name in English or Pinyin, corresponding to the name on the identity document used for verification.<br>Format: CHARSETS_2; 2–64 characters.<br>See <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">Character Sets</a> for the supported characters.<br>Required together with <code>last_name</code> when <code>local_name</code> is omitted.</td></tr><tr><td><code>shareholders[].last_name</code></td><td>string(50)</td><td>C</td><td>Shareholder's legal family name in English or Pinyin, corresponding to the name on the identity document used for verification.<br>Format: CHARSETS_2; 2–64 characters.<br>See <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">Character Sets</a> for the supported characters.<br>Required together with <code>first_name</code> when <code>local_name</code> is omitted.</td></tr><tr><td><code>shareholders[].local_name</code></td><td>string(128)</td><td>C</td><td>Shareholder's full legal name in the local language, exactly as shown on the identity document used for verification.<br>Supports UTF-8/Unicode characters.<br>No character-set restriction.<br>Maximum 128 bytes.<br>Required when <code>first_name</code> and <code>last_name</code> are not both provided. Alternatively, provide both <code>first_name</code> and <code>last_name</code>.</td></tr><tr><td><code>shareholders[].id_type</code></td><td>integer</td><td>M</td><td>Type of identity document submitted for the shareholder.<br>Format: Integer code.<br>See <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/id-type">ID Type</a> for supported values.</td></tr><tr><td><code>shareholders[].id_no</code></td><td>string(6–20)</td><td>M</td><td>Shareholder's identity document number, entered exactly as shown on the document.<br>Length: 6–18 characters.</td></tr><tr><td><code>shareholders[].nationality</code></td><td>string(2)</td><td>M</td><td>Country representing the shareholder's nationality.<br>Format: Two-letter ISO 3166-1 alpha-2 country code.<br>See <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/country-code">Country Code</a> for supported values.</td></tr><tr><td><code>shareholders[].date_birth</code></td><td>string</td><td>O</td><td>Shareholder's date of birth.<br>Format: <code>YYYY-MM-DD</code>.</td></tr><tr><td><code>shareholders[].ownership_percentage</code></td><td>decimal</td><td>O</td><td>Percentage of the corporation owned by the shareholder.<br>Supports up to 6 decimal places.</td></tr></tbody></table>

**Shareholder address object**

| Field                                 | Type          | Requirement | Description                                                                                                                                                                                                                                                                                                        |
| ------------------------------------- | ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `shareholders[].address.line1`        | string(5–128) | C           | <p>Primary address line of the shareholder's current residence, including the street name and building number.<br>Length: 5–128 bytes.<br>Required when <code>full\_address</code> is omitted.</p>                                                                                                                 |
| `shareholders[].address.line2`        | string(5–128) | O           | <p>Additional residential-address information for the shareholder, such as the unit, apartment, floor, or building name.<br>When provided, 5–128 bytes.<br>Optional, including when full\_address is omitted.</p>                                                                                                  |
| `shareholders[].address.postal_code`  | string(4–8)   | O           | <p>ZIP or postal code of the shareholder's residential address.<br>Maximum length: 16 bytes.<br>Optional, including when full\_address is omitted.</p>                                                                                                                                                             |
| `shareholders[].address.city_name`    | string(50)    | C           | <p>City in which the shareholder currently resides.<br>Maximum length: 50 bytes.<br>Required when <code>full\_address</code> is omitted.</p>                                                                                                                                                                       |
| `shareholders[].address.state`        | string(50)    | O           | <p>State, province, or administrative region of the shareholder's residential address.<br>Maximum length: 50 bytes.<br>Optional, including when full\_address is omitted.</p>                                                                                                                                      |
| `shareholders[].address.country_code` | string(2)     | O           | <p>Country of the shareholder's residential address.<br>Format: Two-letter ISO 3166-1 alpha-2 country code.<br>See <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/country-code">Country Code</a> for supported values.<br>Optional, including when full\_address is omitted.</p> |
| `shareholders[].address.full_address` | string(256)   | C           | Complete address as a single string. Maximum length: 256. Required when line1 and city\_name are not used. When full\_address is provided, line1 and city\_name may be omitted. The structured fields line2, postal\_code, and state are optional.                                                                 |

### Complete `biz_data` example

The following example shows the complete business payload before AES encryption.

```json
{
  "request_no": "CORP202610220001",
  "mobile": "+5511999999999",
  "email": "operations@example.com",
  "business_scenes": [
    1005
  ],
  "website_url": "https://www.example.com",
  "corporation": {
    "registration_name": "环球旅行有限公司",
    "name_en": "517NA TRAVEL AGENCY (HK) LIMITED",
    "industry_category": "Online marketplaces",
    "registration_code": "12345678000199",
    "registration_country": "BR",
    "registration_date": "2020-06-15",
    "registration_address": {
      "line1": "100 Avenida Paulista",
      "line2": "10th Floor",
      "postal_code": "01310-100",
      "city_name": "Sao Paulo",
      "state": "SP",
      "country_code": "BR"
    }
  },
  "director": {
    "first_name": "Ana",
    "last_name": "Silva",
    "id_type": 1,
    "id_no": "12345678901",
    "nationality": "BR",
    "date_birth": "1988-05-20",
    "address": {
      "line1": "200 Rua Augusta",
      "line2": "Apartment 12",
      "postal_code": "01304-000",
      "city_name": "Sao Paulo",
      "state": "SP",
      "country_code": "BR"
    }
  },
  "shareholders": [
    {
      "first_name": "Carlos",
      "last_name": "Santos",
      "id_type": 1,
      "id_no": "98765432100",
      "nationality": "BR",
      "ownership_percentage": 35.5,
      "address": {
        "line1": "300 Rua Haddock Lobo",
        "line2": "Suite 5",
        "postal_code": "01414000",
        "city_name": "Sao Paulo",
        "state": "SP",
        "country_code": "BR"
      },
      "date_birth": "1985-03-12"
    }
  ]
}
```

**Request example**

```bash
curl --request POST \
  --url https://rem-api-sandbox.pagsmile.com/remittance/merchant/create-corporation \
  --header 'Content-Type: application/json; charset=UTF-8' \
  --data '{
    "partner_id": "200000001000001",
    "app_id": "2020123456789012345",
    "timestamp": "2026-07-20 10:30:00",
    "version": "2.0",
    "language": "en",
    "random_key": "<RSA-encrypted AES key>",
    "request_id": "f6bed39c-eecf-c1a2-afcb-ba9baec80001",
    "sign_type": "RSA",
    "biz_data": "<AES-encrypted biz_data>"
  }'
```

{% hint style="info" %}
The sandbox `app_id` shown above is an example. Use the `app_id` assigned to your application when testing.
{% endhint %}

**Response**

{% tabs %}
{% tab title="Success" %}
An accepted request returns HTTP `200` with business code `10000`.

The `data` field in the response envelope is AES-encrypted. Decrypt `random_key` with your RSA private key, then use the resulting AES key to decrypt `data`. See [Security](https://docs.pagsmile.com/remittance-api/security) for implementation details.

**Encrypted response example**

```json
{
  "code": "10000",
  "msg": "Success",
  "data": "<AES-encrypted response data>",
  "random_key": "<RSA-encrypted AES key>",
  "sign_type": "RSA",
  "app_id": "2020123456789012345"
}
```

**Decrypted `data` example**

```json
{
  "request_no": "CORP202610220001",
  "merchant_id": 100398,
  "status": 1
}
```

{% endtab %}

{% tab title="Invalid signature" %}
An invalid request signature may return HTTP `400` with the following response:

```json
{
  "code": "40002",
  "msg": "Business Failed",
  "sub_code": "invalid-signature",
  "sub_msg": "invalid signature"
}
```

{% endtab %}
{% endtabs %}

**Response data fields**

| Field         | Type    | Requirement | Description                                                                                                                              |
| ------------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `merchant_id` | long    | M           | <p>Pagsmile-assigned unique identifier of the newly created merchant.<br>Use this value in subsequent merchant-related API requests.</p> |
| `status`      | integer | M           | The Create API response initializes `status` to `1`, indicating that the corporate merchant account is `Enabled`.                        |
| `request_no`  | string  | O           | <p>The request\_no submitted in the corporate merchant creation request.</p><p>Length: 16–36 characters.</p>                             |

**Related APIs**

* [Update Corporate Merchant](https://docs.pagsmile.com/remittance-api/business/onboarding/update-corporation)
* [Query Corporate Merchant](https://docs.pagsmile.com/remittance-api/business/onboarding/query-corporation)
* [Remittance API Common](https://docs.pagsmile.com/remittance-api/common)
