Skip to main content
POST
Create a payment link
Returns a 201 Created with the payment link object. Share the returned url with your customer to collect payment.
merchant_branch_reference_number is required when your API key is scoped to a partner or merchant. Branch-scoped keys can omit it - the link is created against that branch automatically.

Authorizations

X-API-Key
string
header
required

API key enabled for the requested payment-link operation and associated with an eligible partner, merchant, or branch account.

Headers

Idempotency-Key
string
required

Unique client-generated identifier to prevent duplicate operations. Allowed characters: letters, digits, dot (.), hyphen (-), and underscore (_); 8–64 characters. Reusing the same key with an identical body returns the original response; reusing it with a different body returns 409 IDEMPOTENCY_MISMATCH. Keys expire after 24 hours.

Required string length: 8 - 64
Pattern: ^[A-Za-z0-9._-]{8,64}$

Body

application/json
type
enum<string>
required

Usage model for the new link. ONE_TIME accepts one successful payment; MULTI_USE can accept multiple successful payments.

Available options:
ONE_TIME,
MULTI_USE
currency
string
required

ISO 4217 currency code (for example, PHP). Must be a currency enabled for your account.

Required string length: 3
Pattern: ^[A-Z]{3}$
amount
integer<int64>
required

Payment amount in the currency's smallest unit (for PHP, centavos). 150000 = PHP 1,500.00. Integer, range 1 to 99,999,999.

Required range: 1 <= x <= 99999999
Example:

150000

expires_at
string<date-time>
required

RFC 3339 timestamp when the link expires. Required and must be in the future.

Example:

"2026-07-18T00:00:00Z"

merchant_branch_reference_number
string

Branch this link belongs to. Required for partner- and merchant-scoped keys; branch-scoped keys can omit it.

Maximum string length: 100
line_items
object[]

0 to 100 line items. When supplied, amount must equal the sum of unit_price × quantity; an empty array creates an amount-only link.

Maximum array length: 100
max_uses
integer | null

Maximum successful payments allowed. null means unlimited. ONE_TIME links are always 1. Integer >= 1.

Required range: x >= 1
Example:

10

description
string | null

Optional human-readable label. Omit it or send null when no label is needed. When supplied, it must contain at least one non-whitespace character and be at most 500 characters.

Required string length: 1 - 500
order_reference
string | null

Your own reference for reconciliation. Max 100 characters.

Maximum string length: 100
redirect_urls
object

URLs to redirect the customer after payment. Each URL must use HTTPS.

metadata
object

Free-form string key/value pairs. Max 50 keys; each key <=40 characters, each value <=500 characters; <=10,000 serialized bytes.

Response

Payment link created

The payment link object returned by all endpoints.

id
string<uuid>
required

Unique identifier (UUID v7). Use this in API paths and for tracking.

Example:

"550e8400-e29b-41d4-a716-446655440000"

type
enum<string>
required

Payment-link usage model. ONE_TIME accepts one successful payment; MULTI_USE can accept multiple successful payments.

Available options:
ONE_TIME,
MULTI_USE
merchant_branch_reference_number
string
required

Reference number of the branch this link belongs to.

Example:

"SH-ANG-001"

currency
string
required

ISO 4217 currency code.

Example:

"PHP"

amount
integer<int64>
required

Payment amount in the currency's smallest unit (for PHP, centavos). 150000 = PHP 1,500.00.

Example:

150000

line_items
object[]
required

Items the customer is paying for.

description
string | null
required

Merchant-defined description displayed to the customer.

Example:

"Order for wireless earbuds"

status
enum<string>
required

Current payment-link lifecycle status.

Available options:
ACTIVE,
CONSUMED,
EXPIRED,
CANCELLED
expires_at
string<date-time>
required

RFC 3339 timestamp. When the link stops accepting payments.

Example:

"2026-07-18T00:00:00Z"

url
string<uri>
required

The URL to share with customers. Read-only.

Example:

"https://pay.sbx.moduluslabs.io/550e8400-e29b-41d4-a716-446655440000"

max_uses
integer | null
required

Maximum number of successful payments allowed. null means unlimited. ONE_TIME links always have a value of 1.

Example:

10

successful_payment_count
integer
required

Number of successful payments completed so far.

Example:

3

metadata
object
required

Merchant key-value pairs. Max 50 keys, key max 40 Unicode characters, value max 500 Unicode characters, and max 10,000 serialized bytes.

created_at
string<date-time>
required

RFC 3339 timestamp. When the link was created.

Example:

"2026-06-18T10:30:00Z"

updated_at
string<date-time>
required

RFC 3339 timestamp. When the link was last modified.

Example:

"2026-06-18T14:22:00Z"

cancelled_at
string<date-time> | null
required

RFC 3339 timestamp. When the link was cancelled. null if not cancelled.

cancellation_reason
string | null
required

Reason for cancellation. null if not cancelled.

Maximum string length: 500
order_reference
string | null

Merchant's internal order reference for reconciliation.

Maximum string length: 100
Example:

"ORD-2026-0618-001"

redirect_urls
object | null

Customer redirect destinations for successful, declined, or expired outcomes. null when no redirects are configured.