Skip to main content

​
Overview

The Modulus Labs Onboarding API allows you to programmatically onboard merchants to accept various payment methods including terminals, e-commerce, payment links, QR Ph, and Pay with Maya. This API streamlines the KYC (Know Your Customer) process and enables merchants to start accepting payments quickly.

Quick Start

Set up JWT authentication to get started

API Reference

Complete endpoint documentation

Enums Reference

All enumeration values for business types, banks, and more

Error Handling

Handle onboarding errors gracefully

​
API Endpoint

All Onboarding API requests should be made to the sandbox environment: 
https://kyc.sbx.moduluslabs.io
This is the sandbox environment URL. Production credentials and URL will be provided separately when you’re ready to go live.

​
API Philosophy

The Onboarding API is designed for flexibility and compliance:

REST Architecture

Standard REST API with predictable URLs and HTTP methods

JSON Format

All requests and responses use JSON

HTTPS Only

All API requests must be made over HTTPS

JWT Authentication

Secure JWT Bearer Token authentication

Flexible Business Types

Support for Starter, Sole Proprietor, Partnership, and Corporation

KYC Compliance

Document verification and compliance checks

PCI DSS 4.1 Certified

Modulus Labs is PCI DSS 4.1 compliant, ensuring the highest standards of payment security and data protection

​
How It Works

1

Obtain Credentials

Receive your secret key from Modulus Labs to generate JWT tokens for authentication.
2

Create Account

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

Upload Documents

Upload required KYC documents using the File Upload API based on the business type.
4

Onboard Merchant

Submit merchant details, business information, and bank accounts via the Onboard Merchant API.
5

Wait for Approval

Modulus Labs reviews the submission. Status changes from NEW → APPROVED or DECLINED.
6

Handle Updates

If declined, update the merchant information and resubmit for approval.

​
Supported Business Types

The Onboarding API supports four types of businesses, each with different requirements:
Requirements:
  • Barangay Business Permit
  • Minimal documentation
  • No incorporators required
  • No registered address required
Best for: Small businesses, sole traders, and startups
Requirements:
  • Legal name required
  • One incorporator required
  • Registered address required
  • Additional KYC documents
Best for: Individual business owners
Requirements:
  • Legal name required
  • Two incorporators required
  • Registered address required
  • Partnership documents
Best for: Business partnerships and joint ventures
Requirements:
  • Legal name required
  • Minimum three incorporators required
  • Registered address required
  • Corporate registration documents
Best for: Registered corporations and large businesses

​
Payment Methods

Enable merchants to accept payments through various channels:
Payment MethodDescriptionUse Case
TerminalPhysical point-of-sale terminalsIn-store retail transactions
E-commerceOnline payment integrationWeb and mobile checkout
Payment LinkShareable payment URLsInvoice payments, remote sales
QR PhPhilippine QR code standardContactless in-person payments
Pay with MayaMaya wallet integrationE-wallet transactions
Merchants can enable multiple payment methods during onboarding to maximize payment acceptance.

​
Onboarding Status Flow

Understand the merchant approval lifecycle:
Initial status when merchant is first onboarded. Awaiting Modulus Labs approval.
Merchant approved and can start accepting payments. Note: Approved merchants can be declined later if issues are found.
Merchant declined due to missing information or compliance issues. Merchant can update details and resubmit.
Merchant has updated their information after being declined. Awaiting re-approval from Modulus Labs.

​
Key Features

​
Document Verification

All required documents must be uploaded before calling the Onboard Merchant API. The API verifies document completeness based on business type.

​
Multi-Bank Support

Merchants can register multiple settlement accounts including:
  • Traditional bank accounts (150+ supported banks)
  • GCash e-wallet
  • PayMaya e-wallet

​
Flexible Address Management

  • Office Address: Main business location (required for all)
  • Registered Address: Legal registration address (required for non-Starter businesses)

​
Representative Management

  • Authorized Representative: Required for all business types
  • Incorporators: Required based on business type (1 for Sole Proprietor, 2 for Partnership, 3+ for Corporation)
  • Signatories: Optional signatories for business documents

​
Use Cases

Enable your fintech platform to onboard merchants programmatically without manual paperwork.
Aggregate multiple payment providers and onboard sub-merchants at scale.
Allow sellers on your marketplace to accept payments directly by onboarding them as merchants.
Integrate merchant onboarding into your POS system setup workflow.

​
Prerequisites

Before integrating the Onboarding API:
1

Get API Credentials

Contact Modulus Labs to receive your secret key for JWT generation
2

Set Up JWT Generation

Implement JWT token generation using your secret key (see Authentication Guide)
3

Review Business Types

Understand the requirements for each business type (see Enums Reference)
4

Prepare Document Upload

Implement the File Upload API for KYC document submission

​
What’s Next?

Authentication Guide

Learn how to generate JWT Bearer Tokens

Onboard Merchant API

Complete API reference with parameters and examples

Enums Reference

All valid values for business types, banks, and more

Contact Support

Get help from our technical team
Ready to start onboarding merchants? Head to the Authentication Guide to set up JWT tokens.