Create Corporate Merchant
Onboards a corporate merchant by submitting its contact, business, director, and ultimate beneficial owner (UBO) information.
After a successful request, store the returned merchant_id. You will need it to query or update the corporate merchant later.
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. The tables below describe the decrypted biz_data object.
Requirement: M = Mandatory, O = Optional, and C = Conditional. A conditional field is mandatory only when the condition stated in its description applies.
Submit all required fields. Encrypt biz_data, encrypt the AES key into random_key, and sign the request according to the Common request specification.
Request body
Merchant information
mobile
string(16)
O
Mobile phone number of the merchant or primary contact. Format: International number including the country calling code.
email
string(80)
M
Email address of the merchant or primary contact. Format: Valid email address.
business_scenes
list<Integer>
M
List of integer codes identifying the merchant's business scenes.
Format: List<Integer>; submit one or more keys listed in Business Scenes.
Example: [1005].
website_url
string(128)
O
Publicly accessible URL of the merchant's official website. Format: URL; maximum 128 characters.
Corporation information
corporation.registration_name
string(256)
M
Legal name exactly as shown on the official registration documents. Supports UTF-8/Unicode characters. No character-set restriction. Maximum 256 bytes.
corporation.name_en
string(128)
M
English name used for bank account applications.
Format: COMPANY_NAME_EN; ^[A-Za-z0-9][A-Za-z0-9 .,&'()"/-]*$.
The first character must be an English letter or digit.
Maximum 128 bytes.
corporation.industry_category
string
M
Industry category of the corporation's primary business activity. Format: String; submit one of the values listed in Industry Category.
corporation.registration_code
string(32)
M
Official registration number issued to the corporation by the relevant registration authority. Maximum length: 32 bytes.
corporation.registration_country
string(2)
M
Country in which the corporation is legally registered. Format: Two-letter ISO 3166-1 alpha-2 country code. See Country Code for supported values.
Registered address
corporation.registration_address.line1
string(5–128)
M
Primary address line of the corporation's registered office, including the street name and building number. Format: ADDRESS; 5–128 bytes.
corporation.registration_address.line2
string(5–128)
O
Additional registered-address information, such as the unit, suite, floor, or building name. Format: ADDRESS; when provided, 5–128 bytes.
corporation.registration_address.postal_code
string(4–16)
O
ZIP or postal code of the corporation's registered office. Maximum length: 16 bytes.
corporation.registration_address.city_name
string(50)
M
City in which the corporation's registered office is located. Format: STATE_CITY; maximum 50 bytes.
corporation.registration_address.state
string(50)
O
State, province, or administrative region of the corporation's registered office. Format: STATE_CITY; maximum 50 bytes.
corporation.registration_address.country_code
string(2)
M
Country of the corporation's registered-office address. Format: Two-letter ISO 3166-1 alpha-2 country code. See Country Code for supported values.
Director information
director.first_name
string(2–64)
M
Director's legal given name in English or Pinyin, corresponding to the name on the identity document used for verification.
Format: ^[a-zA-Z-,./ ]+$.
Length: 2–64 characters.
director.last_name
string(2–64)
M
Director's legal family name in English or Pinyin, corresponding to the name on the identity document used for verification.
Format: ^[a-zA-Z-,./ ]+$.
Length: 2–64 characters.
director.local_name
string(128)
M
Director's full legal name in the local language, exactly as shown on the identity document used for verification. Supports UTF-8/Unicode characters. No character-set restriction. Maximum 128 bytes.
director.id_type
integer
M
Type of identity document submitted for the director. Format: Integer code. See ID Type for supported values.
director.id_no
string(6–20)
M
Director's identity document number, entered exactly as shown on the document. Length: 6–18 characters.
director.nationality
string(2)
M
Country representing the director's nationality. Format: Two-letter ISO 3166-1 alpha-2 country code. See Country Code for supported values.
director.date_birth
string
M
Director's date of birth.
Format: yyyy-MM-dd.
Director address
director.address.line1
string(5–128)
M
Primary address line of the director's current residence, including the street name and building number. Format: ADDRESS; 5–128 bytes.
director.address.line2
string(5–128)
O
Additional residential-address information for the director, such as the unit, apartment, floor, or building name. Format: ADDRESS; when provided, 5–128 bytes.
director.address.postal_code
string(4–16)
O
ZIP or postal code of the director's residential address. Maximum length: 16 bytes.
director.address.city_name
string(50)
M
City in which the director currently resides. Format: STATE_CITY; maximum 50 bytes.
director.address.state
string(50)
O
State, province, or administrative region of the director's residential address. Format: STATE_CITY; maximum 50 bytes.
director.address.country_code
string(2)
M
Country of the director's residential address. Format: Two-letter ISO 3166-1 alpha-2 country code. See Country Code for supported values.
Shareholder information
shareholders is an array. Submit one object for each UBO or shareholder.
shareholders[].first_name
string(50)
M
Shareholder's legal given name in English or Pinyin, corresponding to the name on the identity document used for verification. Format: CHARSETS_2; 2–64 characters. See Character Sets for the supported characters.
shareholders[].last_name
string(50)
M
Shareholder's legal family name in English or Pinyin, corresponding to the name on the identity document used for verification. Format: CHARSETS_2; 2–64 characters. See Character Sets for the supported characters.
shareholders[].id_type
integer
M
Type of identity document submitted for the shareholder. Format: Integer code. See ID Type for supported values.
shareholders[].id_no
string(6–20)
M
Shareholder's identity document number, entered exactly as shown on the document. Length: 6–18 characters.
shareholders[].nationality
string(2)
M
Country representing the shareholder's nationality. Format: Two-letter ISO 3166-1 alpha-2 country code. See Country Code for supported values.
Shareholder address
shareholders[].address.line1
string(5–128)
M
Primary address line of the shareholder's current residence, including the street name and building number. Format: ADDRESS; 5–128 bytes.
shareholders[].address.line2
string(5–128)
O
Additional residential-address information for the shareholder, such as the unit, apartment, floor, or building name. Format: ADDRESS; when provided, 5–128 bytes.
shareholders[].address.postal_code
string(4–8)
O
ZIP or postal code of the shareholder's residential address. Maximum length: 16 bytes.
shareholders[].address.city_name
string(50)
M
City in which the shareholder currently resides. Format: STATE_CITY; maximum 50 bytes.
shareholders[].address.state
string(50)
O
State, province, or administrative region of the shareholder's residential address. Format: STATE_CITY; maximum 50 bytes.
shareholders[].address.country_code
string(2)
M
Country of the shareholder's residential address. Format: Two-letter ISO 3166-1 alpha-2 country code. See Country Code for supported values.
Plaintext biz_data example
Request example
The sandbox app_id shown above is an example. Use the app_id assigned to your application when testing.
Response
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 for implementation details.
Encrypted response example
Decrypted data example
An invalid request signature may return HTTP 400 with the following response:
Response data fields
merchant_id
long
M
Pagsmile-assigned unique identifier of the newly created merchant. Use this value in subsequent merchant-related API requests.
status
integer
M
Current lifecycle status of the corporate merchant profile. Supported values: TBC before publication.
Related APIs
Last updated