Overview
The Ecom API lets you create hosted payment links — shareable checkout URLs that collect payments online. Create a link, send your customer thehosted_url, and Modulus hosts the checkout page, processes the payment, and notifies you through webhooks.
Authentication
Learn how to authenticate with API keys and understand entity scoping
API Reference
Explore all available endpoints
Webhooks
Receive real-time payment events on your endpoint
Rate Limits
Review per-endpoint rate limits and idempotency rules
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.Base URL
All requests are made against the sandbox base URL: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
Create a payment link
Call Create a Payment Link with the amount, line items, and an
expires_at. You receive a hosted_url.Share the hosted URL
Send the
hosted_url to your customer. They complete payment on the Modulus-hosted checkout page.Receive a webhook
Modulus sends a
payment.succeeded (or payment.declined / payment.failed) event to your configured endpoint. See Webhooks.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).
This documentation targets the sandbox environment. Use
sk_test_ keys to test the full flow — no real money is moved.