Onboard Merchant

Overview

This endpoint onboards a merchant to accept various payment methods. Before calling this API, you must upload all required documents using the File Upload API based on the business type.

Document verification required: The API verifies that all required documents have been uploaded for the selected business type. If documents are missing, the request will fail.

Prerequisites

Create Account

Create a merchant account using the Create Account API to obtain an Account ID

Upload Documents

Upload required KYC documents via File Upload API (requirements vary by business type)

Generate JWT Token

Create a JWT Bearer Token with the Account ID and email (see Authentication)

Submit Onboarding

Call this endpoint with complete merchant details

Authentication

This endpoint requires JWT Bearer Token authentication. See the Authentication Guide for details.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Request Parameters

Core Business Information

businessType

string

required

Type of business entity. Determines which fields are required.Values: STARTER, SOLE_PROPRIETOR, PARTNERSHIP, CORPORATIONSee Business Type Enum for details.Example: "STARTER"

legalName

string

Registered business or legal nameLength: 1-500 charactersRequired when: businessType is SOLE_PROPRIETOR, PARTNERSHIP, or CORPORATIONNot required for: STARTER business typeExample: "Starbucks Corporation"

merchantName

string

required

Merchant display name (used in customer-facing transactions)Length: 1-500 charactersExample: "Starbucks"

modeOfPayments

string[]

required

Payment methods to enable for the merchantValues: TERMINAL, ECOM, PAYMENT_LINK, QRPH, PAY_WITH_MAYAExample: ["ECOM", "QRPH"]See Mode of Payment Enum for descriptions.

currency

string

required

Currency for customer transactions (not settlement)Length: Exactly 3 charactersValues: PHP, USDDefault: PHPExample: "PHP"

tin

string

required

Company Tax Identification NumberLength: 9-12 digitsFormat: Numbers only (no dashes or spaces)Example: "455691852"

industry

string

required

Industry or sector of the businessLength: 1-200 charactersExample: "Food and Beverage"

serviceDescription

string

required

Brief description of business operations and servicesExample: "Coffee shop specializing in specialty beverages and light meals"

isBrickAndMortarStore

boolean

required

Indicates if business has a physical storefrontExample: true

Incorporators

incorporators

array

Array of business incorporators/ownersMin: 0, Max: 5Requirements by business type:

STARTER: Not required (don’t include this field)
SOLE_PROPRIETOR: Exactly 1 incorporator required
PARTNERSHIP: Exactly 2 incorporators required
CORPORATION: Minimum 3 incorporators required

Show Incorporator Object Properties

incorporators[].firstName

string

required

First nameLength: 1-100 characters

incorporators[].middleName

string

Middle nameLength: 1-100 characters

incorporators[].lastName

string

required

Last nameLength: 1-100 characters

incorporators[].emailAddress

string

required

Email addressLength: 1-100 charactersFormat: Valid email

incorporators[].contactNumber

string

required

Contact number (digits only)Length: 1-30 charactersFormat: Numbers only

incorporators[].natureOfWork

string

required

Nature of work or occupationLength: 1-100 characters

incorporators[].sourceOfFunds

string

required

Source of fundsValues: See Source of Funds Enum

incorporators[].nationality

string

required

NationalityLength: 1-100 characters

incorporators[].dateOfBirth

string

required

Date of birthFormat: ISO 8601 (e.g., "1988-02-12T16:00:00.000Z")

incorporators[].address

object

required

Address object

Show Address Properties

city

string

required

City (1-100 characters)

line1

string

required

Street address (1-100 characters)

buildingNameAndNumber

string

Building name and number (1-200 characters)

state

string

required

State or province (1-64 characters)

postalCode

string

required

Postal code (4-10 digits, numbers only)

barangay

string

required

Barangay (1-200 characters)

Signatories

signatories

array

Array of authorized signatoriesMin: 0, Max: 5

Show Signatory Object Properties

signatories[].firstName

string

required

First name (1-100 characters)

signatories[].middleName

string

Middle name (1-100 characters)

signatories[].lastName

string

required

Last name (1-100 characters)

signatories[].position

string

required

Position or title (1-100 characters)

Address

address

object

required

Business address information

Show Office Address (Required)

address.office

object

required

Main office location

city

string

required

City (1-100 characters)

line1

string

required

Street address (1-100 characters)

buildingNameAndNumber

string

Building name and number (1-200 characters)

state

string

required

State or province (1-64 characters)

postalCode

string

required

Postal code (4-10 digits, numbers only)

contactNumber

string

required

Contact number (1-30 digits, numbers only)

barangay

string

required

Barangay (1-200 characters)

Show Registered Address (Conditional)

address.registered

object

Registered business addressRequired for: SOLE_PROPRIETOR, PARTNERSHIP, CORPORATIONNot required for: STARTER

city

string

required

City (1-100 characters)

line1

string

required

Street address (1-100 characters)

buildingNameAndNumber

string

Building name and number (1-200 characters)

state

string

required

State or province (1-64 characters)

postalCode

string

required

Postal code (4-10 digits)

contactNumber

string

required

Contact number (1-30 digits)

barangay

string

required

Barangay (1-200 characters)

Websites

websites

object

Business online presence

Show Website Properties

businessWebsiteUrl

string

Business website URL

isBusinessWebsiteUnderDevelopment

boolean

Whether website is under developmentRequired if: businessWebsiteUrl has a value

facebookUrl

string

Facebook page URL

twitterUrl

string

Twitter profile URL

instagramUrl

string

Instagram profile URL

tiktokUrl

string

TikTok profile URL

Representatives

representatives

object

required

Authorized representatives

Show Authorized Representative (Required)

representatives.authorized

object

required

Primary authorized representative

firstName

string

required

First name (1-100 characters)

middleName

string

Middle name (1-100 characters)

lastName

string

required

Last name (1-100 characters)

emailAddress

string

required

Email address (1-100 characters, valid email format)

contactNumber

string

required

Contact number (1-30 digits, numbers only)

dateOfBirth

string

required

Date of birth (ISO 8601 format)

position

string

required

Position or title (1-100 characters)

Bank Accounts

banks

array

required

Settlement bank accounts (at least one required)

Show Bank Account Properties

banks[].accountDepositType

string

required

Type of settlement accountValues: BANK, GCASH, PAYMAYA, NO_ACCOUNTSee Bank Account Deposit Type

banks[].accountType

string

Account typeValues: SAVINGS, CHECKING_CURRENTRequired when: accountDepositType is BANK

banks[].bankName

string

Bank nameRequired when: accountDepositType is BANK, GCASH, or PAYMAYASee Bank Names Enum for valid values

banks[].accountName

string

Account holder name (1-500 characters)Required when: accountDepositType is BANK, GCASH, or PAYMAYA

banks[].accountNumber

string

Account or mobile number (1-500 characters)Required when: accountDepositType is BANK, GCASH, or PAYMAYA

banks[].currency

string

Settlement currency (3 characters)Required when: accountDepositType is BANK, GCASH, or PAYMAYAValues: PHP, USD

Response

Success Response

Status Code: 200 OK

referenceNumber

string

Unique reference number for the onboarding record generated by Modulus LabsUsage: Keep this reference number for status queries and support requestsExample: "0a17c362-fe5c-4889-9cb5-47df71dac425"

{
  "referenceNumber": "0a17c362-fe5c-4889-9cb5-47df71dac425"
}

{
  "referenceNumber": "0a17c362-fe5c-4889-9cb5-47df71dac425"
}

Error Responses

See Error Handling for complete error code reference.

400 Bad Request - Missing Documents

{
  "code": "20000004",
  "error": "Please upload idsOfValidSignatories file/s before accessing this API.",
  "referenceNumber": "02383ca9-8d72-47e2-9dcb-23e535a96122"
}

Cause: Required documents not uploaded for the business typeSolution: Upload all required documents via File Upload API first

400 Bad Request - Validation Error

{
  "code": "20000005",
  "error": "Invalid incorporator count for CORPORATION business type. Minimum 3 required.",
  "referenceNumber": "abc123-def456-ghi789"
}

Cause: Request parameters don’t meet validation rulesSolution: Check business type requirements and parameter constraints

401 Unauthorized

{
  "code": "20000001",
  "error": "Invalid or expired JWT token",
  "referenceNumber": "xyz789-abc123-def456"
}

Cause: JWT token is invalid or expiredSolution: Generate a new JWT token with correct credentials

Code Examples

# First, generate JWT token (use script or online tool)
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

curl -X POST https://kyc.sbx.moduluslabs.io/v2/onboard \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "businessType": "STARTER",
    "merchantName": "Starbucks",
    "modeOfPayments": ["ECOM"],
    "currency": "PHP",
    "tin": "455691852",
    "industry": "Food and Beverage",
    "serviceDescription": "Specialty coffee retailer",
    "isBrickAndMortarStore": true,
    "address": {
      "office": {
        "city": "Portland",
        "line1": "111 Clarence Basler Rd",
        "state": "Oregon(OR)",
        "postalCode": "97030",
        "contactNumber": "639865748123",
        "barangay": "Wilmington II"
      }
    },
    "representatives": {
      "authorized": {
        "firstName": "David",
        "lastName": "Haven",
        "emailAddress": "[email protected]",
        "contactNumber": "09789364458",
        "dateOfBirth": "1988-02-12T16:00:00.000Z",
        "position": "Accountant"
      }
    },
    "banks": [
      {
        "accountDepositType": "GCASH",
        "bankName": "GCASH",
        "accountName": "Starbucks Corporation",
        "accountNumber": "09260000000"
      }
    ]
  }'

Business Type Examples

Starter Business
Sole Proprietor
Partnership
Corporation

{
  "businessType": "STARTER",
  "merchantName": "My Coffee Shop",
  "modeOfPayments": ["ECOM", "QRPH"],
  "currency": "PHP",
  "tin": "123456789",
  "industry": "Food and Beverage",
  "serviceDescription": "Local coffee shop",
  "isBrickAndMortarStore": true,
  "address": {
    "office": { /* required */ }
  },
  "representatives": {
    "authorized": { /* required */ }
  },
  "banks": [ /* at least one required */ ]
}

Starter businesses don’t require legalName, incorporators, or registered address.

{
  "businessType": "SOLE_PROPRIETOR",
  "legalName": "Juan Dela Cruz Trading",
  "merchantName": "JDC Store",
  "incorporators": [
    {
      "firstName": "Juan",
      "lastName": "Dela Cruz",
      "emailAddress": "[email protected]",
      "contactNumber": "09123456789",
      "natureOfWork": "Retail",
      "sourceOfFunds": "BUSINESS_INCOME",
      "nationality": "Filipino",
      "dateOfBirth": "1985-01-15T00:00:00.000Z",
      "address": { /* required */ }
    }
  ],
  "address": {
    "office": { /* required */ },
    "registered": { /* required */ }
  },
  /* ... other required fields ... */
}

Exactly 1 incorporator required for Sole Proprietor businesses.

{
  "businessType": "PARTNERSHIP",
  "legalName": "Smith & Jones Partnership",
  "merchantName": "S&J Enterprises",
  "incorporators": [
    {
      "firstName": "John",
      "lastName": "Smith",
      /* ... complete details ... */
    },
    {
      "firstName": "Mary",
      "lastName": "Jones",
      /* ... complete details ... */
    }
  ],
  "address": {
    "office": { /* required */ },
    "registered": { /* required */ }
  },
  /* ... other required fields ... */
}

Exactly 2 incorporators required for Partnership businesses.

{
  "businessType": "CORPORATION",
  "legalName": "Acme Corporation Inc.",
  "merchantName": "Acme Corp",
  "incorporators": [
    { /* incorporator 1 - complete details */ },
    { /* incorporator 2 - complete details */ },
    { /* incorporator 3 - complete details */ }
  ],
  "signatories": [
    {
      "firstName": "Jane",
      "lastName": "Doe",
      "position": "CEO"
    }
  ],
  "address": {
    "office": { /* required */ },
    "registered": { /* required */ }
  },
  /* ... other required fields ... */
}

Minimum 3 incorporators required for Corporation businesses.

Best Practices

Upload Documents First

Always upload required KYC documents before calling this API

Validate Before Submit

Validate all parameters client-side to catch errors early

Use Correct Business Type

Choose the appropriate business type and provide required fields

Test with Sandbox

Test thoroughly in sandbox before going to production

Store Reference Number

Save the returned reference number for status tracking

Handle Errors Gracefully

Implement proper error handling and user feedback

Validation Checklist

Before submitting:

Business Type

✓ Business type matches merchant entity type ✓ All required fields for business type are included

Incorporators

✓ Correct number of incorporators for business type ✓ All incorporator fields complete and valid

Addresses

✓ Office address complete ✓ Registered address included if not STARTER ✓ All numeric fields contain only digits

Bank Accounts

✓ At least one bank account provided ✓ Bank name matches account deposit type ✓ All required fields for deposit type included

Documents

✓ All required documents uploaded via File Upload API ✓ Document types match business type requirements

Next Steps

Store Reference Number

Save the reference number for tracking and support requests

Enums Reference

All valid enum values for parameters

Error Handling

Handle onboarding errors properly

Authentication

JWT Bearer Token authentication guide

Authorizations

Authorization

string

header

required

JWT Bearer token authentication

Body

application/json

merchantName

string

required

Trading name or DBA (Doing Business As) name

Maximum string length: 500

modeOfPayments

enum<string>[]

required

List of accepted payment modes

Minimum array length: 1

Available options:

CREDIT_CARD,

DEBIT_CARD,

GCASH,

GRABPAY,

PAYMAYA,

BANK_TRANSFER

currency

enum<string>

required

Primary currency for transactions

Available options:

PHP,

USD

tin

string

required

Tax Identification Number

Maximum string length: 20

industry

string

required

Business industry category

Maximum string length: 200

serviceDescription

string

required

Description of services or products offered

isBrickAndMortarStore

boolean

required

Whether the business has a physical store location

address

object

required

Show child attributes

representatives

object

required

Show child attributes

banks

object[]

required

List of bank accounts for settlement

Required array length: 1 - 2 elements

Show child attributes

legalName

string

Legal registered name of the business (required for non-STARTER types)

Maximum string length: 500

businessHandle

string

Unique business handle/slug for payment links (required for non-STARTER types)

incorporators

object[]

List of business incorporators (for non-STARTER types)

Required array length: 1 - 5 elements

Show child attributes

signatories

object[]

List of authorized signatories

Required array length: 1 - 5 elements

Show child attributes

websites

object

Show child attributes

Response

Onboarding application submitted successfully

onboardingStatus

enum<string>

Initial status of the onboarding application

Available options:

NEW

onboardingReferenceNumber

string<uuid>

Unique reference number for the onboarding record

QR API

Onboarding API

Webhooks API

Overview

Prerequisites

Authentication

Request Parameters

Core Business Information

Incorporators

Signatories

Address

Websites

Representatives

Bank Accounts

Response

Success Response

Error Responses

Code Examples

Business Type Examples

Best Practices

Upload Documents First

Validate Before Submit

Use Correct Business Type

Test with Sandbox

Store Reference Number

Handle Errors Gracefully

Validation Checklist

Next Steps

Store Reference Number

Enums Reference

Error Handling

Authentication

Authorizations

Body

Response

QR API

Onboarding API

Webhooks API

​Overview

​Prerequisites

​Authentication

​Request Parameters

​Core Business Information

​Incorporators

​Signatories

​Address

​Websites

​Representatives

​Bank Accounts

​Response

​Success Response

​Error Responses

​Code Examples

​Business Type Examples

​Best Practices

Upload Documents First

Validate Before Submit

Use Correct Business Type

Test with Sandbox

Store Reference Number

Handle Errors Gracefully

​Validation Checklist

​Next Steps

Store Reference Number

Enums Reference

Error Handling

Authentication

Authorizations

Body

Response

Overview

Prerequisites

Authentication

Request Parameters

Core Business Information

Incorporators

Signatories

Address

Websites

Representatives

Bank Accounts

Response

Success Response

Error Responses

Code Examples

Business Type Examples

Best Practices

Validation Checklist

Next Steps