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

# Introduction

> Create hosted payment links and accept online payments with the Ecom API

## Overview

The Ecom API lets you create **hosted payment links** — shareable checkout URLs that collect payments online. Create a link, send your customer the `hosted_url`, and Modulus hosts the checkout page, processes the payment, and notifies you through webhooks.

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/ecom/authentication">
    Learn how to authenticate with API keys and understand entity scoping
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/ecom/create-payment-link">
    Explore all available endpoints
  </Card>

  <Card title="Webhooks" icon="webhook" href="/docs/ecom/webhooks">
    Receive real-time payment events on your endpoint
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/docs/ecom/authentication">
    Review per-endpoint rate limits and idempotency rules
  </Card>
</CardGroup>

<Note>
  Errors return the format `{ "error": { "code": "...", "message": "...", "correlationId": "..." } }`. Common codes include `invalid_request` (400), `invalid_api_key` (401), `insufficient_permissions` (403), `not_found` (404), `idempotency_mismatch` (409), `invalid_state` (422), and `rate_limited` (429). Each endpoint's reference page lists the codes it can return.
</Note>

## Base URL

All requests are made against the sandbox base URL:

```
https://api.sbx.moduluslabs.io/ecom/v1
```

## Payment link types

| Type        | Behavior                                                             |
| ----------- | -------------------------------------------------------------------- |
| `one_time`  | Accepts exactly one successful payment, then becomes `CONSUMED`.     |
| `multi_use` | Accepts multiple payments, optionally up to a configured `max_uses`. |

## Lifecycle

A payment link moves through the following statuses:

| Status      | Meaning                                    |
| ----------- | ------------------------------------------ |
| `ACTIVE`    | The link is accepting payments.            |
| `CONSUMED`  | The link has reached its usage limit.      |
| `EXPIRED`   | The link has passed its `expires_at` time. |
| `CANCELLED` | The link was manually cancelled.           |

## How it works

<Steps>
  <Step title="Create a payment link">
    Call [Create a Payment Link](/api-reference/ecom/create-payment-link) with the amount, line items, and an `expires_at`. You receive a `hosted_url`.
  </Step>

  <Step title="Share the hosted URL">
    Send the `hosted_url` to your customer. They complete payment on the Modulus-hosted checkout page.
  </Step>

  <Step title="Receive a webhook">
    Modulus sends a `payment.succeeded` (or `payment.declined` / `payment.failed`) event to your configured endpoint. See [Webhooks](/docs/ecom/webhooks).
  </Step>

  <Step title="Reconcile">
    Use the `order_reference` and `metadata` you set at creation to match the payment to your records.
  </Step>
</Steps>

## Working with amounts

All monetary values are integers in the smallest currency unit (centavos for PHP). For example, `150000` represents PHP 1,500.00. The link `amount` must equal the sum of all line items (`unit_price × quantity`).

<Note>
  This documentation targets the sandbox environment. Use `sk_test_` keys to test the full flow — no real money is moved.
</Note>