> 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/query-corporate-merchant.md).

# Query Corporate Merchant

Retrieves the current onboarding profile and review status of a corporate merchant.

{% hint style="info" %}
Pass the `merchant_id` returned by [Create Corporate Merchant](https://docs.pagsmile.com/remittance-api/business/onboarding/create-corporation). The response can be used to review the profile before submitting an update.
{% endhint %}

**Endpoint**

`POST /remittance/merchant/query-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 table below describes the decrypted `biz_data` object.

{% hint style="info" %}
**Response presence:** `M` = Always returned, `O` = May be omitted, and `C` = Returned when the condition stated in the description applies.
{% endhint %}

**Request body**

| Field         | Type | Requirement | Description                                          |
| ------------- | ---- | ----------- | ---------------------------------------------------- |
| `merchant_id` | long | M           | Pagsmile-assigned unique identifier of the merchant. |

**Plaintext `biz_data` example**

```json
{
  "merchant_id": 100398
}
```

**Request example**

```bash
curl --request POST \
  --url https://rem-api-sandbox.pagsmile.com/remittance/merchant/query-corporation \
  --header 'Content-Type: application/json; charset=UTF-8' \
  --data '{
    "partner_id": "200000001000001",
    "app_id": "2020123456789012345",
    "timestamp": "2026-07-20 10:35:00",
    "version": "2.0",
    "language": "en",
    "random_key": "<RSA-encrypted AES key>",
    "request_id": "f6bed39c-eecf-c1a2-afcb-ba9baec80003",
    "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" %}
A successful query 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
{
  "merchant_id": 100398,
  "mobile": "+5511999999999",
  "email": "operations@example.com",
  "business_scenes": [
    1005
  ],
  "website_url": "https://www.example.com",
  "corporation": {
    "corporation_id": 200512,
    "registration_name": "环球旅行有限公司",
    "name_en": "517NA TRAVEL AGENCY (HK) LIMITED",
    "industry_category": "Online marketplaces",
    "registration_code": "12345678000199",
    "registration_country": "BR",
    "registration_date": "2020-06-15",
    "business_documents": [
      {
        "document_type": "ARTICLES_OF_INCORPORATION",
        "file": {
          "file_id": 100901,
          "file_name": "articles-of-incorporation.pdf"
        }
      },
      {
        "document_type": "BANK_STATEMENT",
        "file": {
          "file_id": 100902,
          "file_name": "bank-statement.pdf"
        }
      },
      {
        "document_type": "PROOF_OF_ADDRESS",
        "file": {
          "file_id": 100903,
          "file_name": "proof-of-address.pdf"
        }
      }
    ],
    "registration_address": {
      "line1": "100 Avenida Paulista",
      "line2": "10th Floor",
      "postal_code": "01310-100",
      "city_name": "Sao Paulo",
      "state": "SP",
      "country_code": "BR"
    }
  },
  "director": {
    "director_id": 300624,
    "first_name": "Ana",
    "last_name": "Silva",
    "local_name": "Ana 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": [
    {
      "shareholder_id": 400736,
      "first_name": "Carlos",
      "last_name": "Santos",
      "id_type": 1,
      "id_no": "98765432100",
      "nationality": "BR",
      "birth_date": "1985-03-12",
      "ownership_percentage": 35.5,
      "email": "carlos.santos@example.com",
      "phone_number": "+5511988887777",
      "address": {
        "line1": "300 Rua Haddock Lobo",
        "line2": "Suite 5",
        "postal_code": "01414-000",
        "city_name": "Sao Paulo",
        "state": "SP",
        "country_code": "BR"
      }
    }
  ],
  "status": 1,
  "created_at": "2026-07-20 10:30:00"
}
```

{% 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

The `data` object contains the corporate merchant profile described below.

#### Data object

<table><thead><tr><th width="178.69921875">Field</th><th width="128.0703125">Type</th><th width="138.66015625">Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>merchant_id</code></td><td>long</td><td>M</td><td>Pagsmile-assigned unique identifier of the merchant associated with the returned record.</td></tr><tr><td><code>mobile</code></td><td>string(16)</td><td>C</td><td>Mobile phone number of the merchant or primary contact.<br>Format: International number including the country calling code.<br>Returned for corporations registered in Brazil as a Brazilian mobile number in E.164 format, including the <code>+55</code> country calling code.</td></tr><tr><td><code>email</code></td><td>string(80)</td><td>O</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>C</td><td>Publicly accessible URL of the merchant's official website.<br>Format: URL; maximum 128 characters.<br>Returned for corporations registered in Brazil.</td></tr><tr><td><code>status</code></td><td>integer</td><td>M</td><td>Current activation status of the corporate merchant account. Supported values:<br><code>0</code> — Initial (not yet activated)<br><code>1</code> — Enabled<br><code>2</code> — Disabled<br></td></tr><tr><td><code>onboarding_status</code></td><td>integer</td><td>M</td><td>Current review status of the corporate merchant onboarding application.<br><code>1</code> — <code>APPROVED</code>: The application has been approved.<br><code>2</code> — <code>REJECTED</code>: The application has been rejected.<br><code>4</code> — <code>PENDING</code>: The application has been submitted and is under review.<br><code>5</code>— <code>DECLINED</code>:The application has been declined.</td></tr><tr><td><code>created_at</code></td><td>string</td><td>M</td><td>Date and time when the corporate merchant profile was created.<br>Format: <code>yyyy-MM-dd HH:</code>​<code>mm:ss</code>.</td></tr></tbody></table>

#### Corporation object

| Field                              | Type        | Requirement | Description                                                                                                                                                                                                                                                                                                                   |
| ---------------------------------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `corporation.corporation_id`       | long        | M           | Pagsmile-assigned unique identifier of the corporation record.                                                                                                                                                                                                                                                                |
| `corporation.registration_name`    | string(256) | M           | <p>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.</p>                                                                                                                                                       |
| `corporation.name_en`              | string(128) | M           | <p>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 .,&'()"/-]\*$</code>.<br>The first character must be an English letter or digit.<br>Maximum 128 bytes.</p>    |
| `corporation.industry_category`    | string      | M           | <p>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>.</p>                                                                     |
| `corporation.registration_code`    | string(32)  | M           | <p>Official registration number issued to the corporation by the relevant registration authority.<br>Maximum length: 32 bytes.<br>For a corporation registered in Brazil, this value is its CNPJ.</p>                                                                                                                         |
| `corporation.registration_country` | string(2)   | M           | <p>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.<br>Returns <code>BR</code> for the Brazil onboarding flow.</p> |
| `corporation.registration_date`    | string      | C           | <p>Date on which the corporation was legally established.<br>Format: <code>YYYY-MM-DD</code>.<br>Returned for corporations registered in Brazil.</p>                                                                                                                                                                          |

#### Business documents

`corporation.business_documents` is an array. For Brazil, it must contain one Business document object for each required document type.

Each item in `corporation.business_documents` contains the following fields.

<table><thead><tr><th>Field</th><th width="106.7890625">Type</th><th width="139.8046875">Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>corporation.business_documents[].document_type</code></td><td>string</td><td>M</td><td>Type of corporate document.<br>For Brazil, submit one item for each of the following types: <code>ARTICLES_OF_INCORPORATION</code>, <code>BANK_STATEMENT</code>, and <code>PROOF_OF_ADDRESS</code>.</td></tr><tr><td><code>corporation.business_documents[].file</code></td><td>string</td><td>M</td><td>Document file submitted for the specified document type. See File object.</td></tr><tr><td><code>corporation.business_documents[].file.file_name</code></td><td>string</td><td>M</td><td>Original file name, including the file extension.Supported file formats: PDF, PNG, and JPEG (<code>.jpeg</code> or <code>.jpg</code>).</td></tr></tbody></table>

**Registered address object**

| Field                                           | Type          | Requirement | Description                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------- | ------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `corporation.registration_address.line1`        | string(5–128) | M           | <p>Primary address line of the corporation's registered office, including the street name and building number.<br>Format: <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">ADDRESS</a>; 5–128 bytes.</p>                                                                            |
| `corporation.registration_address.line2`        | string(5–128) | O           | <p>Additional registered-address information, such as the unit, suite, floor, or building name.<br>Format: <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">ADDRESS</a>; when provided, 5–128 bytes.</p>                                                                            |
| `corporation.registration_address.postal_code`  | string(4–16)  | C           | <p>ZIP or postal code of the corporation's registered office.<br>Maximum length: 16 bytes.<br>Returned for corporations registered in Brazil.</p>                                                                                                                                                                             |
| `corporation.registration_address.city_name`    | string(50)    | M           | <p>City in which the corporation's registered office is located.<br>Format: <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">STATE\_CITY</a>; maximum 50 bytes.</p>                                                                                                                 |
| `corporation.registration_address.state`        | string(50)    | C           | <p>State, province, or administrative region of the corporation's registered office.<br>Format: <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">STATE\_CITY</a>; maximum 50 bytes.<br>For Brazil, returns a two-letter value listed in Brazil state codes.</p>                     |
| `corporation.registration_address.country_code` | string(2)     | M           | <p>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>Returns <code>BR</code> for the Brazil onboarding flow.</p> |

#### Director object

| Field                  | Type         | Requirement | Description                                                                                                                                                                                                                                                                              |
| ---------------------- | ------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `director.director_id` | long         | M           | Pagsmile-assigned unique identifier of the director record.                                                                                                                                                                                                                              |
| `director.first_name`  | string(2–64) | M           | <p>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.</p>                                                                                |
| `director.last_name`   | string(2–64) | M           | <p>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.</p>                                                                               |
| `director.local_name`  | string(128)  | M           | <p>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.</p>                                                                   |
| `director.id_type`     | integer      | M           | <p>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.<br>For Brazil, only the <code>ID Card</code> type is supported.</p> |
| `director.id_no`       | string(6–20) | M           | <p>Director's identity document number, entered exactly as shown on the document.<br>Length: 6–18 characters.<br>For Brazil, this value is the director's CPF.</p>                                                                                                                       |
| `director.nationality` | string(2)    | M           | <p>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.</p>                              |
| `director.date_birth`  | string       | M           | <p>Director's date of birth.<br>Format: <code>yyyy-MM-dd</code>.</p>                                                                                                                                                                                                                     |

**Director address object**

| Field                           | Type          | Requirement | Description                                                                                                                                                                                                                                                                                                          |
| ------------------------------- | ------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `director.address.line1`        | string(5–128) | M           | <p>Primary address line of the director's current residence, including the street name and building number.<br>Format: <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">ADDRESS</a>; 5–128 bytes.</p>                                                                      |
| `director.address.line2`        | string(5–128) | O           | <p>Additional residential-address information for the director, such as the unit, apartment, floor, or building name.<br>Format: <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">ADDRESS</a>; when provided, 5–128 bytes.</p>                                             |
| `director.address.postal_code`  | string(4–16)  | C           | <p>ZIP or postal code of the director's residential address.<br>Maximum length: 16 bytes.<br>Returned for corporations registered in Brazil.</p>                                                                                                                                                                     |
| `director.address.city_name`    | string(50)    | M           | <p>City in which the director currently resides.<br>Format: <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">STATE\_CITY</a>; maximum 50 bytes.</p>                                                                                                                        |
| `director.address.state`        | string(50)    | C           | <p>State, province, or administrative region of the director's residential address.<br>Format: <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">STATE\_CITY</a>; maximum 50 bytes.<br>For Brazil, returns a two-letter value listed in Brazil state codes.</p>             |
| `director.address.country_code` | string(2)     | M           | <p>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>Returns <code>BR</code> for the Brazil onboarding flow.</p> |

#### Shareholders

`shareholders` is an array containing the merchant's UBO or shareholder records.

**Shareholder object**

| Field                                 | Type         | Requirement | Description                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------- | ------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shareholders[].shareholder_id`       | long         | O           | Pagsmile-assigned unique identifier of the shareholder record.                                                                                                                                                                                                                                                                     |
| `shareholders[].first_name`           | string(50)   | M           | <p>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.</p>  |
| `shareholders[].last_name`            | string(50)   | M           | <p>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.</p> |
| `shareholders[].id_type`              | integer      | M           | <p>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.<br>For a Brazilian shareholder identified by CPF, this value is the <code>ID Card</code> type.</p>         |
| `shareholders[].id_no`                | string(6–20) | M           | <p>Shareholder's identity document number, entered exactly as shown on the document.<br>Length: 6–18 characters.<br>For Brazil, this value is the shareholder's CPF.</p>                                                                                                                                                           |
| `shareholders[].nationality`          | string(2)    | M           | <p>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.</p>                                                                     |
| `shareholders[].birth_date`           | string       | C           | <p>Shareholder's date of birth.<br>Format: <code>YYYY-MM-DD</code>.<br>Returned for corporations registered in Brazil.</p>                                                                                                                                                                                                         |
| `shareholders[].ownership_percentage` | decimal      | C           | <p>Percentage of the corporation owned by the shareholder.<br>Range: greater than <code>0</code> and less than or equal to <code>100</code>.<br>Returned for corporations registered in Brazil.</p>                                                                                                                                |
| `shareholders[].email`                | string(80)   | C           | <p>Shareholder's email address.<br>Format: Valid email address.<br>Returned for corporations registered in Brazil.</p>                                                                                                                                                                                                             |
| `shareholders[].phone_number`         | string(16)   | C           | <p>Shareholder's or UBO's personal phone number.<br>Returned for corporations registered in Brazil.<br>E.164 format is recommended for submitted values.</p>                                                                                                                                                                       |

**Shareholder address object**

| Field                                 | Type          | Requirement | Description                                                                                                                                                                                                                                                                                                 |
| ------------------------------------- | ------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shareholders[].address.line1`        | string(5–128) | M           | <p>Primary address line of the shareholder's current residence, including the street name and building number.<br>Format: <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">ADDRESS</a>; 5–128 bytes.</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>Format: <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">ADDRESS</a>; when provided, 5–128 bytes.</p>                                 |
| `shareholders[].address.postal_code`  | string(4–16)  | C           | <p>ZIP or postal code of the shareholder's residential address.<br>Maximum length: 16 bytes.<br>Returned for corporations registered in Brazil.</p>                                                                                                                                                         |
| `shareholders[].address.city_name`    | string(50)    | M           | <p>City in which the shareholder currently resides.<br>Format: <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">STATE\_CITY</a>; maximum 50 bytes.</p>                                                                                                            |
| `shareholders[].address.state`        | string(50)    | C           | <p>State, province, or administrative region of the shareholder's residential address.<br>Format: <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/charsets">STATE\_CITY</a>; maximum 50 bytes.<br>For Brazil, returns a two-letter value listed in Brazil state codes.</p> |
| `shareholders[].address.country_code` | string(2)     | M           | <p>Two-letter ISO 3166-1 alpha-2 country code of the shareholder's residential address.<br>Returns <code>BR</code> for the Brazil onboarding flow.</p>                                                                                                                                                      |

### Related APIs

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