> ## Documentation Index
> Fetch the complete documentation index at: https://docs-alpha.pepay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List events

> Returns canonical `PepayEvent` objects produced by the unified outbox/dispatcher.

Ordering:
- Newest first.

Pagination:
- Use `starting_after` to fetch older events.
- Use `ending_before` to fetch newer events.

Scoping:
- `x-api-key` returns events for the merchant account (including commerce invoices when applicable).
- Commerce-scoped keys restrict results to commerce-related events in the key's environment.
- `x-commerce-api-key` is a legacy alias for commerce-scoped keys.




## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/events
openapi: 3.0.0
info:
  title: Pepay API (SDK-scoped)
  version: 1.0.0
  description: API documentation for Pepay API
servers:
  - url: https://api-beta.pepay.io
    description: Beta server
  - url: http://localhost:3000
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Events
    description: Events API (history + debugging) for canonical notification envelopes.
  - name: Metrics
    description: Internal Prometheus metrics (restricted).
  - name: WebSockets
    description: WebSocket streams (upgrade endpoints) and message schemas.
  - name: Commerce - Devnet Simulator
    description: >
      Deterministic devnet-only endpoints for simulating Commerce V2 order state
      transitions.


      Use this when integrating as a merchant on devnet to test your backend/UI
      against realistic order lifecycle changes

      (payment confirmation, settlement gating, placement, tracking,
      cancellation, refunds) without placing real retailer

      orders or sending real on-chain refunds.


      How it works:

      - Requires a devnet `X-Commerce-Api-Key` (merchant-scoped).

      - Only operates on orders created in `networkEnvironment=devnet`.

      - Updates the order using the same reducer/persistence paths used in
      mainnet (provider snapshots are simulated).

      - After each simulation, Pepay emits the normal `commerce.order.updated`
      merchant webhook event.
  - name: Merchant Checkout
    description: >
      Merchant-scoped **three-step** checkout flow:

      1) `POST /api/commerce/merchant/checkout/estimate` — validate items
      against current eligible offers and return `validItems[]` +
      `invalidItems[]`.

      2) `POST /api/commerce/merchant/checkout/address` — attach and validate a
      shipping address for the estimate.

      3) `POST /api/commerce/merchant/checkout/invoice` — create the final
      invoice + commerce order.


      Cart behavior (when `useCart: true`):

      - The estimate call **reads** the saved cart but does **not** remove or
      modify cart items.

      - Items with no eligible offers are returned in `invalidItems[]`.

      - To remove items from the saved cart, call the Merchant Cart APIs (`PUT
      /api/commerce/merchant/carts/items/:itemId` with `quantity: 0`, or `DELETE
      /api/commerce/merchant/carts/items/:itemId`).

      - To exclude items for *this checkout attempt* without mutating the cart,
      use `itemOverrides[]` with `quantity: 0`.
  - name: Payment Sessions
    description: >
      Payor-facing APIs used by the hosted payment page and other embedded
      checkout clients.


      Canonical base path:

      - All documented endpoints are under `/api/v1/payments/*`.


      Authentication:

      - These endpoints do **not** accept merchant API keys or bearer JWTs.

      - Send `x-session-token` and `x-signature` headers on every request (both
      are returned when creating an invoice).


      Typical flow:

      1) Create an invoice (`POST /api/v1/invoices`) → receive `payment_url`,
      `session_token`, `signature`.

      2) Render/open the `payment_url` for the payor.

      3) Fetch invoice context (`GET /api/v1/payments/session-details`).

      4) List supported tokens (`GET /api/v1/payments/available-tokens`).

      5) Allocate a payment address (`POST /api/v1/payments/payment-addresses`)
      → use `ws_connection` for `/ws/payment`.

      6) Track progress via polling (`GET /api/v1/payments/payment-status`)
      and/or websocket (`/ws/payment`).


      Security notes:

      - Treat `session_token` and `signature` as sensitive values (anyone with
      them can read the invoice/payment status).

      - Do not store them in long-lived browser storage; prefer in-memory usage
      on the payment page.
  - name: Quotes
    description: Token settlement quotes and rate calculations
  - name: Webhooks
    description: >
      Webhook endpoint management and delivery history for canonical
      notifications.


      Delivery model:

      - At-least-once delivery; receivers must dedupe by `event.id` (also sent
      as `X-Pepay-Event-ID`).

      - Payloads are canonical `PepayEvent` objects and match websocket
      `event_v1` frames for the same event type.


      Security:

      - Endpoints must be HTTPS.

      - Deliveries are signed using `HMAC_SHA256("${timestamp_ms}.${raw_body}")`
      and sent in `X-Pepay-Signature`.
paths:
  /api/v1/events:
    get:
      tags:
        - Events
      summary: List events
      description: >
        Returns canonical `PepayEvent` objects produced by the unified
        outbox/dispatcher.


        Ordering:

        - Newest first.


        Pagination:

        - Use `starting_after` to fetch older events.

        - Use `ending_before` to fetch newer events.


        Scoping:

        - `x-api-key` returns events for the merchant account (including
        commerce invoices when applicable).

        - Commerce-scoped keys restrict results to commerce-related events in
        the key's environment.

        - `x-commerce-api-key` is a legacy alias for commerce-scoped keys.
      parameters:
        - in: query
          name: type
          schema:
            type: string
          description: >-
            Comma-separated list of event types (supports wildcards like
            invoice.*)
        - in: query
          name: created[gte]
          schema:
            type: integer
        - in: query
          name: created[lte]
          schema:
            type: integer
        - in: query
          name: limit
          schema:
            type: integer
            example: 50
        - in: query
          name: starting_after
          schema:
            type: string
        - in: query
          name: ending_before
          schema:
            type: string
        - in: query
          name: invoice_id
          schema:
            type: string
        - in: query
          name: order_id
          schema:
            type: string
        - in: query
          name: customer_id
          schema:
            type: string
        - in: query
          name: environment
          schema:
            type: string
            enum:
              - devnet
              - mainnet
      responses:
        '200':
          description: List response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Getapiv1eventsResponse200'
      security:
        - merchantApiKey: []
        - commerceApiKey: []
        - bearerAuth: []
components:
  schemas:
    Getapiv1eventsResponse200:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            object:
              type: string
              example: list
            data:
              type: array
              items:
                $ref: '#/components/schemas/PepayEvent'
            has_more:
              type: boolean
              example: false
    PepayEvent:
      type: object
      description: >-
        Canonical Pepay event envelope (shared across webhooks + websocket
        event_v1 streams).
      properties:
        id:
          type: string
          example: evt_1700000000000-123
        object:
          type: string
          example: event
        api_version:
          type: string
          example: '2025-12-16'
        created:
          type: integer
          example: 1700000000
        type:
          type: string
          example: invoice.updated
        livemode:
          type: boolean
          example: false
        pending_webhooks:
          type: integer
          example: 0
        request:
          type: object
          properties:
            id:
              type: string
              nullable: true
            idempotency_key:
              type: string
              nullable: true
        data:
          type: object
          properties:
            object:
              oneOf:
                - $ref: '#/components/schemas/Invoice'
                - $ref: '#/components/schemas/InvoicePayment'
                - $ref: '#/components/schemas/CommerceOrder'
                - $ref: '#/components/schemas/PaymentQuote'
                - $ref: '#/components/schemas/TestPing'
            previous_attributes:
              type: object
              additionalProperties: true
    Invoice:
      type: object
      description: Canonical invoice object (snake_case, usd_millis amounts).
      properties:
        object:
          type: string
          example: invoice
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        merchant_id:
          type: integer
          example: 123
        status:
          type: string
          example: paid
        invoice_type:
          type: string
          example: standard
        currency:
          type: string
          example: usd
        amount:
          type: integer
          example: 10000
        amount_decimal:
          type: string
          example: '10.000'
        amount_paid:
          type: integer
          example: 10000
        amount_paid_decimal:
          type: string
          example: '10.000'
        amount_remaining:
          type: integer
          example: 0
        amount_remaining_decimal:
          type: string
          example: '0.000'
        amount_unit:
          type: string
          example: usd_millis
        customer_id:
          type: string
          nullable: true
        payer_wallet_address:
          type: string
          nullable: true
        payer_wallet_network:
          type: string
          nullable: true
        commerce_order_id:
          type: string
          nullable: true
        environment:
          type: string
          enum:
            - devnet
            - mainnet
        expires_at:
          type: integer
          nullable: true
        created_at:
          type: integer
          nullable: true
        paid_at:
          type: integer
          nullable: true
        last_payment_at:
          type: integer
          nullable: true
        metadata:
          type: object
          additionalProperties: true
    InvoicePayment:
      type: object
      description: >-
        Canonical invoice_payment object (merchant surfaces include settlement
        fields; payor surfaces strip them).
      properties:
        object:
          type: string
          example: invoice_payment
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440111
        invoice_id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        merchant_id:
          type: integer
          example: 123
        invoice_type:
          type: string
          example: standard
        environment:
          type: string
          enum:
            - devnet
            - mainnet
        customer_id:
          type: string
          nullable: true
        commerce_order_id:
          type: string
          nullable: true
        status:
          type: string
          example: confirmed
        settlement_status:
          type: string
          nullable: true
          example: settled
        network:
          type: string
          nullable: true
          example: base
        payer_tx_hash:
          type: string
          nullable: true
        payer_wallet_address:
          type: string
          nullable: true
        payer_wallet_network:
          type: string
          nullable: true
        payer_amount_token:
          type: string
          nullable: true
        currency:
          type: string
          example: usd
        amount:
          type: integer
          example: 10000
        amount_decimal:
          type: string
          example: '10.000'
        amount_unit:
          type: string
          example: usd_millis
        settled_amount:
          type: integer
          nullable: true
          example: 9800
        settled_amount_decimal:
          type: string
          nullable: true
          example: '9.800'
        balance_transaction_id:
          type: string
          nullable: true
          example: bt_550e8400-e29b-41d4-a716-446655440111
        confirmed_at:
          type: integer
          nullable: true
        settled_at:
          type: integer
          nullable: true
        settlement:
          type: object
          nullable: true
          properties:
            summary_status:
              type: string
              nullable: true
              example: settled
            stage:
              type: string
              nullable: true
              example: final
            merchant_settlement_id:
              type: integer
              nullable: true
            settlement_tx_hash:
              type: string
              nullable: true
            network:
              type: string
              nullable: true
              example: base
            status:
              type: string
              nullable: true
        metadata:
          type: object
          additionalProperties: true
    CommerceOrder:
      type: object
      description: >-
        Canonical commerce_order object (provider-safe; based on merchant
        snapshot).
      properties:
        object:
          type: string
          example: commerce_order
        id:
          type: string
          example: ord_123
        merchant_id:
          type: integer
          nullable: true
        invoice_id:
          type: string
          nullable: true
        environment:
          type: string
          enum:
            - devnet
            - mainnet
          nullable: true
        retailer:
          type: string
          nullable: true
          example: amazon
        status:
          type: string
          nullable: true
          example: placed
        substatus:
          type: string
          nullable: true
          example: AWAITING_TRACKING
        actions:
          type: object
          additionalProperties: true
        timeline:
          type: array
          items:
            type: object
        payment:
          type: object
          additionalProperties: true
        fulfillment:
          type: object
          additionalProperties: true
        line_items:
          type: array
          items:
            type: object
        currency:
          type: string
          example: usd
        total_amount:
          type: integer
          example: 10000
        total_amount_decimal:
          type: string
          example: '10.000'
        amount_unit:
          type: string
          example: usd_millis
        customer_id:
          type: string
          nullable: true
        wallet_address:
          type: string
          nullable: true
        wallet_network:
          type: string
          nullable: true
        cancellation_status:
          type: string
          nullable: true
        refund_status:
          type: string
          nullable: true
        refund:
          type: object
          additionalProperties: true
        refund_quote:
          type: object
          nullable: true
          additionalProperties: true
        created_at:
          type: integer
          nullable: true
        updated_at:
          type: integer
          nullable: true
    PaymentQuote:
      type: object
      description: Canonical payment_quote object for /ws/payment?format=event_v1.
      properties:
        object:
          type: string
          example: payment_quote
        invoice_id:
          type: string
        network:
          type: string
        supported_token_id:
          type: integer
          nullable: true
        settlement_token_id:
          type: integer
          nullable: true
        currency:
          type: string
          example: usd
        amount_remaining:
          type: integer
          example: 10000
        amount_remaining_decimal:
          type: string
          example: '10.000'
        amount_unit:
          type: string
          example: usd_millis
        estimated_token_amount_remaining:
          type: string
          nullable: true
        exchange_rate:
          type: string
          nullable: true
        quote_last_updated_at:
          type: integer
          nullable: true
        quote_valid_until:
          type: integer
          nullable: true
        quote_expires_in_seconds:
          type: integer
          nullable: true
        quote_status:
          type: string
          nullable: true
        status_code:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
        retryable:
          type: boolean
          nullable: true
        retry_after_seconds:
          type: integer
          nullable: true
    TestPing:
      type: object
      properties:
        object:
          type: string
          example: test_ping
        id:
          type: string
          example: tp_123
        message:
          type: string
          example: pong
        created_at:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for wallet authentication
    merchantApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for server-to-server operations (scope=merchant or commerce)
    commerceApiKey:
      type: apiKey
      in: header
      name: x-commerce-api-key
      description: >-
        Legacy alias for commerce-scoped API keys. Prefer `x-api-key` with
        scope=commerce.

````