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.

Quickstart

Onboard a merchant end to end in five calls

API Reference

Complete endpoint documentation

Enums Reference

All enumeration values for business types, banks, and more

Error Handling

Handle onboarding errors gracefully

​
How onboarding works

A merchant is onboarded in a few server-side calls, then reviewed by Modulus before going live. Onboarding does not send status webhooks, so you poll for the result.
1

Create the merchant account

POST /v2/onboard/signup returns an account id. You authenticate with a Bearer JWT provisioned at onboarding (see Authentication).
2

Upload KYC documents

POST /v2/onboard/{id}/files (multipart) uploads the required identity and business documents.
3

Submit the application

POST /v2/onboard with the business details. The application starts at status NEW.
4

Poll for the result

GET /v2/onboard/{ref}/status until the status is APPROVED or DECLINED.
5

Resubmit if declined

If DECLINED, PUT /v2/onboard/{ref} with corrections; the status moves to PENDING for re-review.

​
API Endpoint

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

​
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:
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.

​
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.