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

> Hosted payment links: create a shareable checkout URL and accept online payments

## Overview

A payment link is a Modulus-hosted checkout URL. You create a link server-side, send your customer the returned `url`, and Modulus hosts the checkout page and processes the payment. No frontend code is required.

<Card title="Quickstart" icon="rocket" href="/docs/ecom/quickstart">
  Create a link and take your first payment in five minutes.
</Card>

## Payment link types

| Type        | Behavior                                                                                                                                                |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ONE_TIME`  | Accepts one successful payment, then becomes `CONSUMED`. Concurrent attempts can overshoot the final slot; `max_uses` is not a strict concurrency lock. |
| `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, description, and an `expires_at`. You receive a `url`.
  </Step>

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

  <Step title="Return the customer">
    After payment, the customer is redirected to the matching URL in `redirect_urls` (`success`, `declined`, or `expired`).
  </Step>

  <Step title="Reconcile">
    [Retrieve the payment link](/api-reference/ecom/retrieve-payment-link) to read its current `status` and `successful_payment_count`, and match the payment to your records using the `order_reference` and `metadata` you set at creation.
  </Step>
</Steps>

## Amounts and line items

Amounts are integers in the currency's smallest unit (for PHP, centavos); see [Working with amounts](/docs/ecom/introduction#working-with-amounts). When `line_items` are supplied, the link `amount` must equal their sum (`unit_price` times `quantity`). An empty array creates an amount-only link.