> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moduluslabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding API

> Onboard merchants to accept payments through Modulus Labs

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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/docs/onboarding/authentication">
    Set up JWT authentication to get started
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/onboarding/onboard-merchant">
    Complete endpoint documentation
  </Card>

  <Card title="Enums Reference" icon="list" href="/docs/onboarding/enums">
    All enumeration values for business types, banks, and more
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/docs/errors">
    Handle onboarding errors gracefully
  </Card>
</CardGroup>

## API Endpoint

All Onboarding API requests should be made to the sandbox environment:

```bash theme={null}
https://kyc.sbx.moduluslabs.io
```

<Note>
  This is the sandbox environment URL. Production credentials and URL will be provided separately when you're ready to go live.
</Note>

## API Philosophy

The Onboarding API is designed for flexibility and compliance:

<CardGroup cols={3}>
  <Card title="REST Architecture" icon="globe">
    Standard REST API with predictable URLs and HTTP methods
  </Card>

  <Card title="JSON Format" icon="brackets-curly">
    All requests and responses use JSON
  </Card>

  <Card title="HTTPS Only" icon="lock">
    All API requests must be made over HTTPS
  </Card>

  <Card title="JWT Authentication" icon="shield">
    Secure JWT Bearer Token authentication
  </Card>

  <Card title="Flexible Business Types" icon="building">
    Support for Starter, Sole Proprietor, Partnership, and Corporation
  </Card>

  <Card title="KYC Compliance" icon="file-check">
    Document verification and compliance checks
  </Card>

  <Card title="PCI DSS 4.1 Certified" icon="badge-check">
    Modulus Labs is PCI DSS 4.1 compliant, ensuring the highest standards of payment security and data protection
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="Obtain Credentials">
    Receive your secret key from Modulus Labs to generate JWT tokens for authentication.
  </Step>

  <Step title="Create Account">
    Create a merchant account using the [Create Account API](/api-reference/onboarding/create-account) to obtain an Account ID.
  </Step>

  <Step title="Upload Documents">
    Upload required KYC documents using the [File Upload API](/api-reference/onboarding/upload-onboarding-files) based on the business type.
  </Step>

  <Step title="Onboard Merchant">
    Submit merchant details, business information, and bank accounts via the [Onboard Merchant API](/api-reference/onboarding/onboard-merchant).
  </Step>

  <Step title="Wait for Approval">
    Modulus Labs reviews the submission. Status changes from NEW → APPROVED or DECLINED.
  </Step>

  <Step title="Handle Updates">
    If declined, update the merchant information and resubmit for approval.
  </Step>
</Steps>

## Supported Business Types

The Onboarding API supports four types of businesses, each with different requirements:

<AccordionGroup>
  <Accordion title="Starter Business" icon="seedling">
    **Requirements:**

    * Barangay Business Permit
    * Minimal documentation
    * No incorporators required
    * No registered address required

    **Best for:** Small businesses, sole traders, and startups
  </Accordion>

  <Accordion title="Sole Proprietor" icon="user">
    **Requirements:**

    * Legal name required
    * One incorporator required
    * Registered address required
    * Additional KYC documents

    **Best for:** Individual business owners
  </Accordion>

  <Accordion title="Partnership" icon="handshake">
    **Requirements:**

    * Legal name required
    * Two incorporators required
    * Registered address required
    * Partnership documents

    **Best for:** Business partnerships and joint ventures
  </Accordion>

  <Accordion title="Corporation" icon="building">
    **Requirements:**

    * Legal name required
    * Minimum three incorporators required
    * Registered address required
    * Corporate registration documents

    **Best for:** Registered corporations and large businesses
  </Accordion>
</AccordionGroup>

## Payment Methods

Enable merchants to accept payments through various channels:

| Payment Method    | Description                      | Use Case                       |
| ----------------- | -------------------------------- | ------------------------------ |
| **Terminal**      | Physical point-of-sale terminals | In-store retail transactions   |
| **E-commerce**    | Online payment integration       | Web and mobile checkout        |
| **Payment Link**  | Shareable payment URLs           | Invoice payments, remote sales |
| **QR Ph**         | Philippine QR code standard      | Contactless in-person payments |
| **Pay with Maya** | Maya wallet integration          | E-wallet transactions          |

<Tip>
  Merchants can enable multiple payment methods during onboarding to maximize payment acceptance.
</Tip>

## Onboarding Status Flow

Understand the merchant approval lifecycle:

```mermaid theme={null}
graph LR
    A[NEW] --> B[APPROVED]
    A --> C[DECLINED]
    C --> D[Update Details]
    D --> E[PENDING]
    E --> B
    E --> C
```

<AccordionGroup>
  <Accordion title="NEW" icon="circle-plus">
    Initial status when merchant is first onboarded. Awaiting Modulus Labs approval.
  </Accordion>

  <Accordion title="APPROVED" icon="circle-check">
    Merchant approved and can start accepting payments. Note: Approved merchants can be declined later if issues are found.
  </Accordion>

  <Accordion title="DECLINED" icon="circle-xmark">
    Merchant declined due to missing information or compliance issues. Merchant can update details and resubmit.
  </Accordion>

  <Accordion title="PENDING" icon="clock">
    Merchant has updated their information after being declined. Awaiting re-approval from Modulus Labs.
  </Accordion>
</AccordionGroup>

## 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

<AccordionGroup>
  <Accordion title="Fintech Platforms">
    Enable your fintech platform to onboard merchants programmatically without manual paperwork.
  </Accordion>

  <Accordion title="Payment Aggregators">
    Aggregate multiple payment providers and onboard sub-merchants at scale.
  </Accordion>

  <Accordion title="E-commerce Marketplaces">
    Allow sellers on your marketplace to accept payments directly by onboarding them as merchants.
  </Accordion>

  <Accordion title="POS Systems">
    Integrate merchant onboarding into your POS system setup workflow.
  </Accordion>
</AccordionGroup>

## Prerequisites

Before integrating the Onboarding API:

<Steps>
  <Step title="Get API Credentials">
    Contact Modulus Labs to receive your secret key for JWT generation
  </Step>

  <Step title="Set Up JWT Generation">
    Implement JWT token generation using your secret key (see [Authentication Guide](/docs/onboarding/authentication))
  </Step>

  <Step title="Review Business Types">
    Understand the requirements for each business type (see [Enums Reference](/docs/onboarding/enums))
  </Step>

  <Step title="Prepare Document Upload">
    Implement the File Upload API for KYC document submission
  </Step>
</Steps>

## What's Next?

<CardGroup cols={2}>
  <Card title="Authentication Guide" icon="key" href="/docs/onboarding/authentication">
    Learn how to generate JWT Bearer Tokens
  </Card>

  <Card title="Onboard Merchant API" icon="user-plus" href="/api-reference/onboarding/onboard-merchant">
    Complete API reference with parameters and examples
  </Card>

  <Card title="Enums Reference" icon="list-ol" href="/docs/onboarding/enums">
    All valid values for business types, banks, and more
  </Card>

  <Card title="Contact Support" icon="envelope" href="mailto:support@moduluslabs.io">
    Get help from our technical team
  </Card>
</CardGroup>

<Note>
  **Ready to start onboarding merchants?** Head to the [Authentication Guide](/docs/onboarding/authentication) to set up JWT tokens.
</Note>