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

# Step 2 - Set shipping address

> Sets and validates shipping address for the order.
Requires a valid estimate ID from step 1.




## OpenAPI

````yaml /api-reference/openapi.json post /api/commerce/merchant/checkout/address
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/checkout/address:
    post:
      tags:
        - Merchant Checkout
      summary: Step 2 - Set shipping address
      description: |
        Sets and validates shipping address for the order.
        Requires a valid estimate ID from step 1.
      operationId: setMerchantAddress
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommerceMerchantCheckoutAddressRequest'
            examples:
              set_address:
                summary: Set shipping address for the estimate
                value:
                  customer_id: cust_123456
                  estimateId: 550e8400-e29b-41d4-a716-446655440000
                  address:
                    first_name: Jane
                    last_name: Doe
                    street_address: 123 Main St
                    address_line2: Apt 4B
                    city: Miami
                    state: FL
                    zip_code: '33101'
                    country: US
                    phone: '+13055550123'
                    email: jane@example.com
      responses:
        '200':
          description: Address set successfully
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/PostapicommercemerchantcheckoutaddressResponse200
              examples:
                address_set:
                  summary: Address standardized + shipping options returned
                  value:
                    success: true
                    data:
                      addressId: 550e8400-e29b-41d4-a716-446655440222
                      validated: true
                      standardized:
                        first_name: Jane
                        last_name: Doe
                        street_address: 123 Main St
                        address_line2: Apt 4B
                        city: Miami
                        state: FL
                        zip_code: '33101'
                        country: US
                        phone: '+13055550123'
                        email: jane@example.com
                      shippingOptions:
                        - id: standard
                          name: Standard Shipping
                          price: 5.99
                          estimatedDays: 5-7 business days
      security:
        - commerceApiKey: []
        - merchantApiKey: []
components:
  schemas:
    CommerceMerchantCheckoutAddressRequest:
      description: >-
        Step 2 request. Sets and validates the shipping address for an existing
        estimate.
      allOf:
        - $ref: '#/components/schemas/CommerceCustomerIdentifier'
        - type: object
          required:
            - estimateId
            - address
          properties:
            estimateId:
              type: string
              format: uuid
            address:
              type: object
              required:
                - first_name
                - last_name
                - street_address
                - city
                - state
                - zip_code
                - country
                - email
              properties:
                first_name:
                  type: string
                  example: Jane
                last_name:
                  type: string
                  example: Doe
                street_address:
                  type: string
                  example: 123 Main St
                address_line2:
                  type: string
                  nullable: true
                  example: Apt 4B
                city:
                  type: string
                  example: Miami
                state:
                  type: string
                  example: FL
                zip_code:
                  type: string
                  example: '33101'
                country:
                  type: string
                  example: US
                phone:
                  type: string
                  nullable: true
                  example: '+13055550123'
                email:
                  type: string
                  format: email
                  example: jane@example.com
    PostapicommercemerchantcheckoutaddressResponse200:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/CommerceMerchantCheckoutAddressResult'
    CommerceCustomerIdentifier:
      description: Customer identification for merchant-scoped commerce APIs.
      oneOf:
        - type: object
          required:
            - customer_id
          properties:
            customer_id:
              type: string
              example: cust_123456
        - type: object
          required:
            - wallet_address
            - wallet_network
          properties:
            wallet_address:
              type: string
              example: '0x0000000000000000000000000000000000000001'
            wallet_network:
              type: string
              enum:
                - ethereum
                - base
                - solana
                - avalanche
                - ton
                - bsc
                - arbitrum
                - optimism
                - cardano
                - sui
              example: bsc
    CommerceMerchantCheckoutAddressResult:
      type: object
      description: Step 2 result. Address ID is used in Step 3 invoice creation.
      properties:
        addressId:
          type: string
          format: uuid
        validated:
          type: boolean
          example: true
        standardized:
          $ref: '#/components/schemas/CommerceMerchantCheckoutAddressStandardized'
        shippingOptions:
          type: array
          items:
            $ref: '#/components/schemas/CommerceMerchantCheckoutShippingOption'
    CommerceMerchantCheckoutAddressStandardized:
      type: object
      description: Standardized address fields returned after validation.
      properties:
        first_name:
          type: string
          example: Jane
        last_name:
          type: string
          example: Doe
        street_address:
          type: string
          example: 123 Main St
        address_line2:
          type: string
          nullable: true
          example: Apt 4B
        city:
          type: string
          example: Miami
        state:
          type: string
          example: FL
        zip_code:
          type: string
          example: '33101'
        country:
          type: string
          example: US
        phone:
          type: string
          nullable: true
          example: '+13055550123'
        email:
          type: string
          format: email
          example: jane@example.com
    CommerceMerchantCheckoutShippingOption:
      type: object
      description: Shipping option (best-effort placeholder).
      properties:
        id:
          type: string
          example: standard
        name:
          type: string
          example: Standard Shipping
        price:
          type: number
          example: 5.99
        estimatedDays:
          type: string
          example: 5-7 business days
  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)

````