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

# List Payment Links

> Return a paginated list of payment links accessible by your API key

<Info>
  Results are returned in the `data` array with a `pagination` object. Links are scoped automatically to your API key's entity level.
</Info>

## Filtering

| Parameter                          | Description                                                            |
| ---------------------------------- | ---------------------------------------------------------------------- |
| `status`                           | `ACTIVE`, `CONSUMED`, `EXPIRED`, or `CANCELLED`                        |
| `merchant_branch_reference_number` | Filter by branch. Only applicable for partner- or merchant-level keys. |
| `created_after` / `created_before` | ISO 8601 timestamps to bound the creation window                       |

## Cursor pagination

To fetch the next page, pass the `next_cursor` value from the previous response as the `cursor` query parameter:

```bash theme={null}
curl 'https://api.sbx.moduluslabs.io/ecom/v1/checkout?status=ACTIVE&page_size=20&cursor=Y3JlYXRlZF9hdHwxNzE4NzA0MjAwMDAwfDE5' \
  -H 'Authorization: Bearer sk_test_your_api_key_here'
```

When `has_more` is `false`, you have reached the last page.

## Required scope

`payment_links.read`


## OpenAPI

````yaml api-reference/ecom/openapi.json GET /checkout
openapi: 3.0.3
info:
  title: Ecom API
  description: >-
    REST API for creating and managing hosted payment links (checkout). Generate
    a shareable, hosted checkout URL, accept one-time or multi-use payments, and
    reconcile results through webhooks.


    **Entity scoping:** Every API key is scoped to an entity in the organization
    hierarchy (Partner → Merchant → Branch). Data access is automatically
    restricted to the key's level.


    **Amounts:** All monetary values are integers in the smallest currency unit
    (centavos for PHP). `150000` represents PHP 1,500.00.


    **Idempotency:** Mutating `POST` requests require an `Idempotency-Key`
    header to safely retry without creating duplicates.
  version: 1.0.0
  contact:
    name: API Support
    email: support@moduluslabs.io
  license:
    name: Proprietary
servers:
  - url: https://api.sbx.moduluslabs.io/ecom/v1
    description: Sandbox
security:
  - BearerAuth: []
tags:
  - name: Payment Links
    description: Create and manage hosted payment links
paths:
  /checkout:
    get:
      tags:
        - Payment Links
      summary: List payment links
      description: >-
        Returns a paginated list of payment links accessible by your API key.
        Results use opaque cursor-based pagination.


        Requires the `payment_links.read` scope.
      operationId: listPaymentLinks
      parameters:
        - name: status
          in: query
          required: false
          description: Filter by payment link status.
          schema:
            $ref: '#/components/schemas/PaymentLinkStatus'
        - name: merchant_branch_reference_number
          in: query
          required: false
          description: >-
            Filter by branch reference number. Only applicable for partner- or
            merchant-level keys.
          schema:
            type: string
        - name: created_after
          in: query
          required: false
          description: ISO 8601 timestamp. Only return links created after this time.
          schema:
            type: string
            format: date-time
        - name: created_before
          in: query
          required: false
          description: ISO 8601 timestamp. Only return links created before this time.
          schema:
            type: string
            format: date-time
        - name: page_size
          in: query
          required: false
          description: Number of results per page.
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: cursor
          in: query
          required: false
          description: Opaque pagination token from a previous response's `next_cursor`.
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of payment links
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLinkListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    PaymentLinkStatus:
      type: string
      description: Current status of the payment link.
      enum:
        - ACTIVE
        - CONSUMED
        - EXPIRED
        - CANCELLED
    PaymentLinkListResponse:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PaymentLink'
        pagination:
          $ref: '#/components/schemas/Pagination'
    PaymentLink:
      type: object
      description: The payment link object returned by all endpoints.
      required:
        - id
        - type
        - merchant_branch_reference_number
        - merchant_branch_name
        - currency
        - amount
        - line_items
        - status
        - expires_at
        - hosted_url
        - successful_payment_count
        - metadata
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier (UUID v4). Use this in API paths and for tracking.
          example: 550e8400-e29b-41d4-a716-446655440000
        type:
          $ref: '#/components/schemas/PaymentLinkType'
        merchant_branch_reference_number:
          type: string
          description: Reference number of the branch this link belongs to.
          example: SH-ANG-001
        merchant_branch_name:
          type: string
          description: Display name of the branch. Read-only.
          example: SM City Angeles - Branch 1
        currency:
          type: string
          description: ISO 4217 currency code.
          example: PHP
        amount:
          type: integer
          format: int64
          description: >-
            Payment amount in the smallest currency unit (centavos for PHP).
            `150000` = PHP 1,500.00.
          example: 150000
        line_items:
          type: array
          description: Items the customer is paying for.
          items:
            $ref: '#/components/schemas/LineItem'
        description:
          type: string
          nullable: true
          description: Merchant-defined description displayed to the customer.
          example: Order for wireless earbuds
        order_reference:
          type: string
          nullable: true
          maxLength: 100
          description: Merchant's internal order reference for reconciliation.
          example: ORD-2026-0618-001
        redirect_urls:
          allOf:
            - $ref: '#/components/schemas/RedirectUrls'
          nullable: true
        status:
          $ref: '#/components/schemas/PaymentLinkStatus'
        expires_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp. When the link stops accepting payments.
          example: '2026-07-18T00:00:00Z'
        hosted_url:
          type: string
          format: uri
          description: The URL to share with customers. Read-only.
          example: >-
            https://pay.moduluslabs.io/checkout/550e8400-e29b-41d4-a716-446655440000
        max_uses:
          type: integer
          nullable: true
          description: >-
            Maximum number of successful payments allowed. `null` = unlimited.
            Only applicable for `multi_use` links.
          example: 10
        successful_payment_count:
          type: integer
          description: Number of successful payments completed so far.
          example: 3
        metadata:
          type: object
          description: >-
            Merchant key-value pairs. Max 50 keys, key max 40 characters, value
            max 500 characters.
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp. When the link was created.
          example: '2026-06-18T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp. When the link was last modified.
          example: '2026-06-18T14:22:00Z'
        cancelled_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            ISO 8601 timestamp. When the link was cancelled. `null` if not
            cancelled.
        cancellation_reason:
          type: string
          nullable: true
          maxLength: 500
          description: Reason for cancellation. `null` if not cancelled.
    Pagination:
      type: object
      required:
        - page_size
        - has_more
        - next_cursor
      properties:
        page_size:
          type: integer
          description: Number of results requested per page.
          example: 20
        has_more:
          type: boolean
          description: >-
            Whether more results are available. When `false`, you have reached
            the last page.
          example: true
        next_cursor:
          type: string
          nullable: true
          description: >-
            Opaque token to fetch the next page. Pass it as the `cursor` query
            parameter.
          example: Y3JlYXRlZF9hdHwxNzE4NzA0MjAwMDAwfDE5
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error code.
              example: invalid_request
            message:
              type: string
              description: Human-readable explanation of the error.
              example: Amount must be greater than zero.
            correlationId:
              type: string
              format: uuid
              description: Unique request identifier. Include this in support requests.
              example: a084e7ab-e80e-4232-b6b7-280167765883
    PaymentLinkType:
      type: string
      description: >-
        `one_time` accepts exactly one successful payment then becomes
        `CONSUMED`. `multi_use` accepts multiple payments, optionally up to
        `max_uses`.
      enum:
        - one_time
        - multi_use
    LineItem:
      type: object
      required:
        - sku
        - name
        - unit_price
        - quantity
      properties:
        sku:
          type: string
          description: Merchant-defined SKU or product identifier.
          example: PROD-001
        name:
          type: string
          description: Product name displayed to the customer.
          example: Wireless Earbuds
        unit_price:
          type: integer
          format: int64
          minimum: 1
          description: >-
            Price per unit in the smallest currency unit. Must be greater than
            0.
          example: 75000
        quantity:
          type: integer
          minimum: 1
          description: Number of units. Must be greater than 0.
          example: 2
        metadata:
          type: object
          description: Optional key-value pairs for this line item.
          additionalProperties:
            type: string
    RedirectUrls:
      type: object
      description: URLs to redirect the customer after payment. Each URL must use HTTPS.
      properties:
        success:
          type: string
          format: uri
          description: URL to redirect after a successful payment.
          example: https://merchant.com/payment/success
        declined:
          type: string
          format: uri
          description: URL to redirect after a declined payment.
          example: https://merchant.com/payment/declined
        expired:
          type: string
          format: uri
          description: URL to redirect when the payment link has expired.
          example: https://merchant.com/payment/expired
  responses:
    BadRequest:
      description: The request body or parameters failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalid_request:
              summary: Validation failed
              value:
                error:
                  code: invalid_request
                  message: Amount must equal the sum of all line items.
                  correlationId: a084e7ab-e80e-4232-b6b7-280167765883
            idempotency_key_required:
              summary: Missing Idempotency-Key header
              value:
                error:
                  code: idempotency_key_required
                  message: The Idempotency-Key header is required for this request.
                  correlationId: a084e7ab-e80e-4232-b6b7-280167765883
    Unauthorized:
      description: The API key is missing, expired, revoked, or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_api_key
              message: API key is missing or invalid.
              correlationId: a084e7ab-e80e-4232-b6b7-280167765883
    Forbidden:
      description: The API key does not have the required scope for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: insufficient_permissions
              message: API key lacks the required scope for this operation.
              correlationId: a084e7ab-e80e-4232-b6b7-280167765883
    RateLimited:
      description: >-
        Too many requests. Retry after the time indicated in the `Retry-After`
        header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded. Retry after 23 seconds.
              correlationId: a084e7ab-e80e-4232-b6b7-280167765883
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        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.

````