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

# Get merchant order details (scoped)

> Returns the canonical **merchant-facing** snapshot for a single commerce order.

This is the same shape delivered in `commerce.order.*` webhook events and is safe to build merchant UI against.

Auth:
- Server-to-server: `X-Commerce-Api-Key`
- Dashboard/user: `Authorization: Bearer <JWT>`




## OpenAPI

````yaml /api-reference/openapi.json get /api/commerce/merchant/orders/{orderId}
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/commerce/merchant/orders/{orderId}:
    get:
      tags:
        - Orders
      summary: Get merchant order details (scoped)
      description: >
        Returns the canonical **merchant-facing** snapshot for a single commerce
        order.


        This is the same shape delivered in `commerce.order.*` webhook events
        and is safe to build merchant UI against.


        Auth:

        - Server-to-server: `X-Commerce-Api-Key`

        - Dashboard/user: `Authorization: Bearer <JWT>`
      operationId: getCommerceMerchantOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Order snapshot
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/GetapicommercemerchantordersorderIdResponse200
              examples:
                placed_with_tracking:
                  summary: Placed order with tracking + line item image
                  value:
                    success: true
                    data:
                      orderId: 550e8400-e29b-41d4-a716-446655440000
                      invoiceId: 550e8400-e29b-41d4-a716-446655440111
                      merchantId: 123
                      networkEnvironment: devnet
                      retailer: amazon
                      createdAt: 1765843200
                      updatedAt: 1765843800
                      customerId: cust_123456
                      walletAddress: '0x0000000000000000000000000000000000000001'
                      walletNetwork: bsc
                      status: placed
                      substatus: AWAITING_TRACKING
                      actions:
                        canCancel: false
                      timeline:
                        - status: processing
                          timestamp: 1765843260
                          message: Payment received, processing order
                        - status: placed
                          timestamp: 1765843320
                          message: Order placed with retailer
                      payment:
                        status: paid
                        txHash: 0xpay
                        settlement:
                          status: settled
                          txHash: 0xsettle
                          network: bsc
                      fulfillment:
                        shipments:
                          - shipmentId: ship_123
                            carrier: UPS
                            trackingNumber: 1Z999AA10123456784
                            carrierTrackingUrl: https://t.17track.net/en#nums=1Z999AA10123456784
                            deliveryStatus: In Transit
                            retailerTrackingNumber: TBA111189418000
                            retailerTrackingUrl: https://www.amazon.com/progress-tracker/...
                            obtainedAt: 1765843500
                      lineItems:
                        - productId: B08N5WRWNW
                          title: Item
                          imageUrl: https://example.com/product.jpg
                          quantity: 1
                          price: '9.00'
                          status: processing
                      shippingAddress: null
                      cancellationStatus: none
                      refundStatus: NONE
                      totalAmountUsd: '10.00'
                      commerceFeeUsd: '1.00'
                      refund:
                        status: NONE
                        amountUsd: null
                        feeUsd: null
                        destinationWalletAddressBsc: '0x0000000000000000000000000000000000000001'
                        txHash: null
        '401':
          description: Missing or invalid commerce API key
        '403':
          description: Commerce API key suspended or expired
        '404':
          description: Order not found for this merchant
      security:
        - bearerAuth: []
        - commerceApiKey: []
        - merchantApiKey: []
components:
  schemas:
    GetapicommercemerchantordersorderIdResponse200:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/CommerceMerchantOrderSnapshot'
    CommerceMerchantOrderSnapshot:
      type: object
      description: >-
        Merchant-facing commerce order snapshot (scoped by merchant +
        environment).
      properties:
        orderId:
          type: string
          format: uuid
        invoiceId:
          type: string
          format: uuid
        merchantId:
          type: integer
          example: 123
        networkEnvironment:
          type: string
          enum:
            - devnet
            - mainnet
          example: devnet
        retailer:
          type: string
          nullable: true
          example: amazon
        createdAt:
          type: integer
          nullable: true
        updatedAt:
          type: integer
          nullable: true
        customerId:
          type: string
          nullable: true
          example: cust_123456
        walletAddress:
          type: string
          nullable: true
          example: '0x0000000000000000000000000000000000000001'
        walletNetwork:
          type: string
          nullable: true
          example: bsc
        status:
          type: string
          enum:
            - pending_payment
            - processing
            - placed
            - shipped
            - cancelled
            - failed
          example: placed
        substatus:
          type: string
          nullable: true
          example: AWAITING_TRACKING
        actions:
          type: object
          properties:
            canCancel:
              type: boolean
              example: false
        timeline:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
                example: placed
              timestamp:
                type: integer
                example: 1765843200
              message:
                type: string
                example: Order placed with retailer
        payment:
          type: object
          properties:
            status:
              type: string
              enum:
                - paid
                - unpaid
              example: paid
            txHash:
              type: string
              nullable: true
              example: 0xpay
            settlement:
              type: object
              properties:
                status:
                  type: string
                  nullable: true
                  example: settled
                txHash:
                  type: string
                  nullable: true
                  example: 0xsettle
                network:
                  type: string
                  nullable: true
                  example: bsc
        fulfillment:
          type: object
          properties:
            shipments:
              type: array
              items:
                $ref: '#/components/schemas/CommerceMerchantShipment'
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/CommerceMerchantOrderLineItem'
        shippingAddress:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/CommerceMerchantShippingAddress'
        cancellationStatus:
          type: string
          nullable: true
          example: none
        refundStatus:
          type: string
          nullable: true
          example: NONE
        totalAmountUsd:
          type: string
          example: '10.00'
        commerceFeeUsd:
          type: string
          example: '1.00'
        refund:
          type: object
          properties:
            status:
              type: string
              nullable: true
              example: NONE
            amountUsd:
              type: string
              nullable: true
              example: '9.00'
            feeUsd:
              type: string
              nullable: true
              example: '1.00'
            destinationWalletAddressBsc:
              type: string
              nullable: true
              example: '0x0000000000000000000000000000000000000001'
            txHash:
              type: string
              nullable: true
              example: 0xrefund
        refundQuote:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/CommerceMerchantRefundQuote'
    CommerceMerchantShipment:
      type: object
      description: Merchant-facing shipment/tracking snapshot.
      properties:
        shipmentId:
          type: string
          example: ship_123
        carrier:
          type: string
          nullable: true
          example: UPS
        trackingNumber:
          type: string
          nullable: true
          example: 1Z999AA10123456784
        carrierTrackingUrl:
          type: string
          nullable: true
          example: https://t.17track.net/en#nums=1Z999AA10123456784
        deliveryStatus:
          type: string
          nullable: true
          example: In Transit
        retailerTrackingNumber:
          type: string
          nullable: true
          example: TBA111189418000
        retailerTrackingUrl:
          type: string
          nullable: true
          example: https://www.amazon.com/progress-tracker/...
        obtainedAt:
          type: integer
          nullable: true
          example: 1765843200
    CommerceMerchantOrderLineItem:
      type: object
      description: Merchant-facing commerce order line item.
      properties:
        productId:
          type: string
          example: B08N5WRWNW
        title:
          type: string
          example: Item
        imageUrl:
          type: string
          nullable: true
          example: https://example.com/product.jpg
        quantity:
          type: integer
          example: 1
        price:
          type: string
          example: '9.00'
          description: Unit price in USD (string with 2 decimals).
        status:
          type: string
          nullable: true
          example: processing
    CommerceMerchantShippingAddress:
      type: object
      description: Validated shipping address snapshot.
      properties:
        addressId:
          type: string
          example: addr_123
        firstName:
          type: string
          example: Jane
        lastName:
          type: string
          example: Doe
        addressLine1:
          type: string
          example: 123 Main St
        addressLine2:
          type: string
          nullable: true
          example: Apt 4B
        city:
          type: string
          example: Miami
        state:
          type: string
          example: FL
        zipCode:
          type: string
          example: '33101'
        country:
          type: string
          example: US
        email:
          type: string
          example: jane@example.com
        phoneNumber:
          type: string
          nullable: true
          example: '+13055550123'
        validated:
          type: boolean
          example: true
        validatedAt:
          type: integer
          nullable: true
          example: 1765843200
    CommerceMerchantRefundQuote:
      type: object
      description: Deterministic refund quote (amounts are stable snapshots for the order).
      properties:
        originalAmountUsd:
          type: string
          example: '10.00'
        feeAmountUsd:
          type: string
          example: '1.00'
        refundAmountUsd:
          type: string
          example: '9.00'
        refundToken:
          type: object
          properties:
            network:
              type: string
              example: bsc
            symbol:
              type: string
              example: USD1
        refundDestination:
          type: object
          properties:
            network:
              type: string
              example: bsc
            address:
              type: string
              nullable: true
              example: '0x0000000000000000000000000000000000000001'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for wallet authentication
    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.
    merchantApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for server-to-server operations (scope=merchant or commerce)

````