Skip to main content
POST
/
checkout
Create a payment link
curl --request POST \
  --url https://api.sbx.moduluslabs.io/ecom/v1/checkout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "merchant_branch_reference_number": "SH-ANG-001",
  "type": "multi_use",
  "currency": "PHP",
  "amount": 150000,
  "line_items": [
    {
      "sku": "PROD-001",
      "name": "Wireless Earbuds",
      "unit_price": 75000,
      "quantity": 2,
      "metadata": {
        "color": "black"
      }
    }
  ],
  "description": "Order for wireless earbuds",
  "order_reference": "ORD-2026-0618-001",
  "redirect_urls": {
    "success": "https://merchant.com/payment/success",
    "declined": "https://merchant.com/payment/declined",
    "expired": "https://merchant.com/payment/expired"
  },
  "expires_at": "2026-07-18T00:00:00Z",
  "max_uses": 10,
  "metadata": {
    "campaign_id": "summer-2026",
    "internal_ref": "CRM-4821"
  }
}
'
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "merchant_branch_reference_number": "SH-ANG-001",
    "merchant_branch_name": "SM City Angeles - Branch 1",
    "currency": "PHP",
    "amount": 150000,
    "line_items": [
      {
        "sku": "PROD-001",
        "name": "Wireless Earbuds",
        "unit_price": 75000,
        "quantity": 2,
        "metadata": {}
      }
    ],
    "expires_at": "2026-07-18T00:00:00Z",
    "hosted_url": "https://pay.moduluslabs.io/checkout/550e8400-e29b-41d4-a716-446655440000",
    "successful_payment_count": 3,
    "metadata": {},
    "created_at": "2026-06-18T10:30:00Z",
    "updated_at": "2026-06-18T14:22:00Z",
    "description": "Order for wireless earbuds",
    "order_reference": "ORD-2026-0618-001",
    "redirect_urls": {
      "success": "https://merchant.com/payment/success",
      "declined": "https://merchant.com/payment/declined",
      "expired": "https://merchant.com/payment/expired"
    },
    "max_uses": 10,
    "cancelled_at": "2023-11-07T05:31:56Z",
    "cancellation_reason": "<string>"
  }
}
Returns a 201 Created with the full payment link object wrapped in data. Share the returned hosted_url with your customer to collect payment.

​
Idempotency

This endpoint requires an Idempotency-Key header — a unique client-generated identifier (letters, digits, dot, hyphen, underscore; 8–64 characters, e.g. your own order ID). Reusing the same key with an identical body returns the original response without creating a duplicate. Reusing it with a different body returns 409 idempotency_mismatch. Keys expire after 24 hours.

​
Amount validation

The amount must equal the sum of every line item (unit_price × quantity). For the example below, 75000 × 2 = 150000.
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.

​
Required scope

payment_links.create

Authorizations

​
Authorization
string
header
required

API key passed as a bearer token. Use sk_live_ keys for production and sk_test_ keys for sandbox. Keys are provisioned during merchant onboarding.

Headers

​
Idempotency-Key
string
required

Unique client-generated identifier to prevent duplicate operations. Allowed characters: letters, digits, dot (.), hyphen (-), and underscore (_); 8–64 characters — e.g. your own order ID. 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.

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

Body

application/json
​
type
enum<string>
required

one_time accepts exactly one successful payment then becomes CONSUMED. multi_use accepts multiple payments, optionally up to max_uses.

Available options:
one_time,
multi_use
​
currency
string
required

ISO 4217 currency code. Currently supported: PHP.

Example:

"PHP"

​
amount
integer<int64>
required

Total amount in the smallest currency unit. Must equal the sum of all line items (unit_price × quantity).

Required range: x >= 1
Example:

150000

​
line_items
object[]
required

1 to 100 line items.

Required array length: 1 - 100 elements
​
expires_at
string<date-time>
required

ISO 8601 timestamp. Must be in the future.

Example:

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

​
merchant_branch_reference_number
string

Required if your API key is scoped to a partner or merchant. Not required for branch-scoped keys.

Example:

"SH-ANG-001"

​
max_uses
integer | null

For multi_use only. Omit or set to null for unlimited. Must be greater than 1. Ignored for one_time links.

Required range: x >= 2
Example:

10

​
description
string

Free-form text displayed to the customer on the checkout page.

Example:

"Order for wireless earbuds"

​
order_reference
string

Your internal order identifier.

Maximum string length: 100
Example:

"ORD-2026-0618-001"

​
redirect_urls
object

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

​
metadata
object

Key-value pairs for your own use. Max 50 keys, key max 40 characters, value max 500 characters.

Response

Payment link created

​
data
object
required

The payment link object returned by all endpoints.