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

# List all payment orders

> Retrieves a list of all payment orders for the specified merchant. Supports filtering by customer, status, date range, and search (by customer email, order number, invoice number, or merchant reference). This is an internal endpoint.



## OpenAPI

````yaml /api-reference/orchestrator-openapi.json get /v2/payment-orders
openapi: 3.0.0
info:
  title: Payment Orchestrator API
  description: API documentation for the Payment Orchestrator service
  version: 1.0.0
servers:
  - url: https://api.sandbox.cheqpay.mx/pos
    description: Sandbox environment
  - url: https://prod.cheqpay.mx/pos
    description: Production environment
security:
  - ApiKeyAuth: []
    MerchantIdAuth: []
tags:
  - name: Customer
    description: Customer management endpoints (v1)
  - name: Customer V2
    description: >-
      Customer management endpoints (v2) - merchant-scoped, no external ID
      required
  - name: Payment Order
    description: Payment order management endpoints
  - name: Checkout
    description: Payment checkout endpoints
  - name: Payment Method
    description: Payment method management endpoints
  - name: Subscription Plan
    description: Subscription plan management endpoints for recurring payments
  - name: Subscription
    description: Subscription management endpoints for recurring billing
  - name: Subscription Invoice
    description: Subscription invoice management endpoints
paths:
  /v2/payment-orders:
    get:
      tags:
        - Payment Order
      summary: List all payment orders
      description: >-
        Retrieves a list of all payment orders for the specified merchant.
        Supports filtering by customer, status, date range, and search (by
        customer email, order number, invoice number, or merchant reference).
        This is an internal endpoint.
      parameters:
        - name: customerId
          in: query
          required: false
          schema:
            type: string
          description: Customer ID to filter payment orders (optional)
        - name: includeRelatedCustomers
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: >-
            When true and customerId is provided, also includes orders from
            related customers linked via the sourceId chain. Defaults to false.
        - name: excludeOverdue
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: >-
            When true, only returns orders that are not overdue: due date unset
            or still in the future. Defaults to false (no due-date restriction).
        - name: status
          in: query
          required: false
          schema:
            type: string
          description: Payment order status to filter by (optional)
        - name: dateFrom
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            Start date for filtering payment orders by creation date (ISO 8601
            format, optional)
        - name: dateTo
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            End date for filtering payment orders by creation date (ISO 8601
            format, optional)
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: >-
            Search term to filter payment orders by customer email, order
            number, invoice number, or merchant reference (case-insensitive,
            optional)
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Number of orders to return per page (max 100)
        - name: sortField
          in: query
          required: false
          schema:
            type: string
            enum:
              - createdAt
            default: createdAt
          description: Sort field (e.g., createdAt)
        - name: sortOrder
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          description: Sort order (ascending or descending)
      responses:
        '200':
          description: Payment orders retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentOrderResponse'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                        description: Current page number
                      limit:
                        type: integer
                        description: Number of items per page
                      total:
                        type: integer
                        description: Total number of payment orders
                      count:
                        type: integer
                        description: Number of items in current page
                      totalPages:
                        type: integer
                        description: Total number of pages
        '400':
          description: Validation failed - missing required parameter or invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
components:
  schemas:
    PaymentOrderResponse:
      type: object
      required:
        - id
        - externalId
        - amount
        - currency
        - status
        - refundedAmount
        - payments
      properties:
        id:
          type: string
          description: Unique payment order ID
          example: 856b4a29-a7e5-4726-87d4-77e55d5ecfbf
        externalId:
          type: string
          description: External payment order ID from merchant system
          example: ORDER-123
        refundedAmount:
          type: number
          description: Total refunded amount across all payments (in cents)
          example: 0
        amount:
          type: number
          description: Payment amount
          example: 100.5
        subtotalAmount:
          type: number
          nullable: true
          description: >-
            Pre-surcharge subtotal in minor units. Equals `amount` when no
            surcharge applies. Null on legacy orders predating subtotal
            tracking.
          example: 100000
        surchargeAmount:
          type: number
          nullable: true
          description: >-
            Surcharge component of `amount` in minor units, or null when none.
            On split-tender orders this grows as each partial's surcharge lands
            and shrinks on refund.
          example: 5000
        surchargeRate:
          type: number
          nullable: true
          description: >-
            Snapshot of the merchant's surcharge rate (percent) captured at
            order creation, or null when no surcharge applies.
          example: 5
        amountPaid:
          type: number
          description: >-
            Cumulative sum of captured amounts across this order's Payments (in
            minor units). Historical ledger — on re-activable orders that get
            partially refunded and re-paid, this can exceed `amount`. Use
            `amountPending` for live balance.
          example: 50000
        amountPending:
          type: number
          description: >-
            Outstanding amount left to cover net of refunds (in minor units).
            Computed as `max(0, amount - (amountPaid - amountRefunded))`.
            Reaches 0 when the order is fully paid net of any refunds — the only
            live-balance field on the snapshot.
          example: 55000
        allowPartials:
          type: boolean
          description: >-
            True when the order accepts multiple Payments via `POST
            /v2/payment-orders/{id}/payments`. Set at creation time.
          example: false
        invoiceType:
          type: string
          enum:
            - PUE
            - PPD
          nullable: true
          description: >-
            CFDI invoice type derived from the flow. `PUE` for legacy 1:1 orders
            (single CFDI). `PPD` for split-tender orders (parent + REP per
            capture + credit note per refund). Null when the order is not
            fiscal.
          example: PUE
        invoiceStatus:
          type: string
          enum:
            - PENDING
            - INVOICED
            - FAILED
          nullable: true
          description: >-
            Overall CFDI status. For PPD this reflects the parent CFDI; use
            `invoiceSummary` for per-REP / per-credit-note granularity.
          example: INVOICED
        fiscalUuid:
          type: string
          nullable: true
          description: >-
            SAT UUID (folio fiscal) of the parent CFDI. Present once
            `invoiceStatus = INVOICED`.
          example: b1c2d3e4-f5g6-h7i8-j9k0-l1m2n3o4p5q6
        complements:
          type: array
          description: >-
            PPD-only: emitted REP complements (Recibos Electrónicos de Pago).
            One row per successfully-stamped Payment. Always present as an array
            (empty `[]` for PUE / non-fiscal orders).
          items:
            $ref: '#/components/schemas/InvoiceComplement'
        creditNotes:
          type: array
          description: >-
            PPD-only: emitted Notas de Crédito. One row per successfully-stamped
            refund event. Always present as an array (empty `[]` for PUE /
            non-fiscal orders).
          items:
            $ref: '#/components/schemas/InvoiceComplement'
        invoiceSummary:
          $ref: '#/components/schemas/InvoiceSummary'
          description: >-
            PPD-only: aggregated stamping progress. Undefined for PUE and
            non-fiscal orders — the UI should treat its absence as 'not a PPD
            order'.
        currency:
          type: string
          description: Three-letter currency code (ISO 4217)
          example: USD
        status:
          type: string
          enum:
            - PENDING
            - PROCESSING
            - REFERENCE_GENERATED
            - AUTHORIZED
            - PARTIALLY_AUTHORIZED
            - ACTION_REQUIRED
            - COMPLETED
            - PARTIALLY_PAID
            - CANCELLATION_REQUESTED
            - CANCELLED
            - FAILED
            - REFUND_PROCESSING
            - PARTIALLY_REFUNDED
            - REFUNDED
          description: Payment order status
        orderNumber:
          type: string
          description: Unique order number generated by the system
          example: C25123101
        invoiceNumber:
          type: string
          nullable: true
          maxLength: 64
          description: >-
            Merchant-provided invoice number; shown to customers instead of
            orderNumber when present
          example: INV-2026-001
        description:
          type: string
          description: Payment description
          example: 'Payment for order #123'
        metadata:
          type: object
          nullable: true
          description: Arbitrary JSON metadata stored with the payment order
          additionalProperties: true
          example:
            orderId: ORD-123
            source: web
        billingAddressLine:
          type: string
          description: Billing address line
          example: 123 Main St
        billingCity:
          type: string
          description: Billing city
          example: New York
        billingState:
          type: string
          description: Billing state
          example: NY
        billingPostalCode:
          type: string
          description: Billing postal code
          example: '10001'
        billingCountry:
          type: string
          description: Billing country code
          example: US
        customer:
          type: object
          properties:
            externalId:
              type: string
              description: External customer ID from merchant system
              example: CUST-123
            firstName:
              type: string
              description: Customer's first name
              example: John
            lastName:
              type: string
              description: Customer's last name
              example: Doe
            email:
              type: string
              format: email
              description: Customer's email address
              example: john.doe@example.com
            phoneNumber:
              type: string
              description: Customer's phone number
              example: '+1234567890'
            active:
              type: boolean
              description: Whether the customer is active
              example: true
            createdAt:
              type: string
              format: date-time
              description: Customer creation timestamp
              example: '2024-03-20T10:00:00Z'
            updatedAt:
              type: string
              format: date-time
              description: Customer last update timestamp
              example: '2024-03-20T10:00:00Z'
        dueDate:
          type: string
          format: date-time
          nullable: true
          description: >-
            Due date for the payment order. Used for payment reminder
            notifications.
          example: '2026-04-15T00:00:00.000Z'
        createdAt:
          type: string
          format: date-time
          description: Payment order creation timestamp
          example: '2024-03-20T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: Payment order last update timestamp
          example: '2024-03-20T10:00:00Z'
        paymentMethod:
          type: object
          required:
            - id
            - type
          properties:
            id:
              type: string
              format: uuid
              description: Payment method unique identifier
              example: 856b4a29-a7e5-4726-87d4-77e55d5ecfbf
            type:
              type: string
              enum:
                - CARD
                - SPEI
                - CIE_CASH_NET
              description: Payment method type
            cardDetails:
              type: object
              nullable: true
              description: Card details (present when payment method type is 'card')
              properties:
                id:
                  type: string
                  description: Card ID
                type:
                  type: string
                  description: Card type
                  example: CREDIT
                bin:
                  type: string
                  description: Bank identification number (first 6 digits)
                  example: '411111'
                last4:
                  type: string
                  description: Last 4 digits of card
                  example: '1111'
                brand:
                  type: string
                  description: Card brand
                  example: VISA
                country:
                  type: string
                  description: Card issuing country
                  example: US
                issuerBank:
                  type: string
                  description: Card issuing bank
                  example: CHASE
                expMonth:
                  type: integer
                  description: Card expiry month
                  example: 12
                expYear:
                  type: integer
                  description: Card expiry year
                  example: 2025
                createdAt:
                  type: string
                  format: date-time
                  description: Creation timestamp
                updatedAt:
                  type: string
                  format: date-time
                  description: Last update timestamp
            speiDetails:
              type: object
              nullable: true
              description: SPEI details (present when payment method type is 'spei')
              properties:
                id:
                  type: string
                  format: uuid
                  description: SPEI payment method detail ID
                clabe:
                  type: string
                  description: CLABE account number for SPEI transfer (18 digits)
                  example: '123456789012345678'
                createdAt:
                  type: string
                  format: date-time
                  description: Creation timestamp
                updatedAt:
                  type: string
                  format: date-time
                  description: Last update timestamp
            cieDetails:
              type: object
              nullable: true
              description: >-
                CIE Cash Net details (present when payment method type is
                'cie_cash_net')
              properties:
                id:
                  type: string
                  format: uuid
                  description: CIE payment method detail ID
                reference:
                  type: string
                  description: CIE reference number for cash payment at convenience stores
                  example: CIE0000000001
                convenio:
                  type: string
                  description: BBVA account number for same-bank payments
                  example: '0123456789'
                clabe:
                  type: string
                  description: >-
                    Interbank account number (CLABE) for transfers from other
                    banks
                  example: '012345678901234567'
                createdAt:
                  type: string
                  format: date-time
                  description: Creation timestamp
                updatedAt:
                  type: string
                  format: date-time
                  description: Last update timestamp
        payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
          description: >-
            List of payments for a payment order, Note: this information is only
            available on the order details endpoint
    ValidationError:
      type: object
      description: Validation error response
      required:
        - message
        - errors
      properties:
        message:
          type: string
          description: Error message
          example: Validation failed
        errors:
          type: array
          description: List of validation errors
          items:
            type: object
            properties:
              field:
                type: string
                description: Field that failed validation
                example: name
              message:
                type: string
                description: Validation error message
                example: Required
      example:
        message: Validation failed
        errors:
          - field: name
            message: Required
    UnauthorizedError:
      type: object
      description: Unauthorized error response
      properties:
        message:
          type: string
          description: Error message
          example: Invalid api key
      example:
        message: Invalid api key
    InternalError:
      type: object
      description: Error response
      properties:
        message:
          type: string
          description: Error message
          example: Error message
      example:
        message: Error message
    InvoiceComplement:
      type: object
      description: >-
        One PPD complement (REP or CREDIT_NOTE). Surfaced in `complements` /
        `creditNotes` on GET /:id and in `/cfdi-url` responses.
      required:
        - id
        - paymentId
        - amount
        - status
      properties:
        id:
          type: string
          format: uuid
          description: >-
            PaymentInvoiceComplement row id (internal). Use as a stable key in
            the UI.
          example: 9c8b7a6d-5e4f-3c2b-1a0f-9e8d7c6b5a4d
        paymentId:
          type: string
          format: uuid
          description: Payment this complement is attached to.
          example: a0b0c9d4-6ce9-40e4-873a-e234c1d93639
        paymentEventId:
          type: string
          format: uuid
          nullable: true
          description: >-
            Set only for credit notes — links the note to the specific refund
            event. Null for REPs.
          example: 20912eee-6047-40c7-97b4-48501bb36ef4
        amount:
          type: number
          description: >-
            Amount of the complement in minor units. For REPs = the Payment's
            captured amount; for credit notes = the refund amount (subtotal
            portion).
          example: 25000
        fiscalUuid:
          type: string
          nullable: true
          description: >-
            SAT UUID (folio fiscal) of this complement. Present when `status =
            EMITTED`.
          example: b1c2d3e4-f5g6-h7i8-j9k0-l1m2n3o4p5q6
        fiscalInvoiceId:
          type: string
          nullable: true
          description: Facturapi invoice id for this complement.
          example: 6a710705bd1842a3122c70ff
        pdfKey:
          type: string
          nullable: true
          description: >-
            S3 key where the CFDI PDF is stored. Do NOT build presigned URLs
            from this on the client — call `/cfdi-url` instead.
          example: invoices/mch_test_001/order-uuid/rep-payment-uuid.pdf
        status:
          type: string
          enum:
            - PENDING
            - EMITTED
            - FAILED
          description: >-
            Lifecycle of the complement. Only EMITTED rows have `fiscalUuid` and
            `pdfKey`.
          example: EMITTED
        emittedAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            Timestamp when Facturapi returned success. Null when status !=
            EMITTED.
          example: '2026-08-06T05:37:35.760Z'
        createdAt:
          type: string
          format: date-time
          description: Row creation timestamp.
          example: '2026-08-06T05:37:30.100Z'
    InvoiceSummary:
      type: object
      description: >-
        PPD-only aggregate view of stamping progress. Frontend uses this to
        render chips (green = fully stamped, yellow = has failures + retry
        button, blue = pending) without iterating over `complements` /
        `creditNotes` manually.
      required:
        - capturedCount
        - emittedRepCount
        - pendingRepCount
        - failedRepCount
        - refundEventCount
        - emittedCreditNoteCount
        - pendingCreditNoteCount
        - failedCreditNoteCount
        - isFullyStamped
      properties:
        capturedCount:
          type: integer
          description: >-
            Payments whose status makes them REP-eligible (CAPTURED /
            PARTIALLY_CAPTURED / SETTLED / PARTIALLY_REFUNDED / REFUNDED).
          example: 4
        emittedRepCount:
          type: integer
          description: Captured Payments that already have an EMITTED REP row.
          example: 3
        pendingRepCount:
          type: integer
          description: Captured Payments with no complement row at all — never attempted.
          example: 0
        failedRepCount:
          type: integer
          description: >-
            Captured Payments whose REP attempt is currently in FAILED state —
            retry via POST /stamp.
          example: 1
        refundEventCount:
          type: integer
          description: >-
            Successful refund events across all Payments (expected credit-note
            count).
          example: 1
        emittedCreditNoteCount:
          type: integer
          description: Refund events with an EMITTED credit-note row.
          example: 1
        pendingCreditNoteCount:
          type: integer
          description: Refund events with no credit-note row at all — never attempted.
          example: 0
        failedCreditNoteCount:
          type: integer
          description: >-
            Refund events whose credit-note attempt is currently in FAILED state
            — retry via POST /stamp.
          example: 0
        isFullyStamped:
          type: boolean
          description: >-
            True only when REPs and credit notes are both fully caught up (no
            pending, no failed). Use as the primary signal for the green 'fully
            stamped' UI chip.
          example: false
    Payment:
      type: object
      required:
        - id
        - status
        - paymentMethodType
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the payment
          example: 856b4a29-a7e5-4726-87d4-77e55d5ecfbf
        status:
          type: string
          enum:
            - CREATED
            - PENDING_AUTHORIZATION
            - AUTHORIZED
            - PARTIALLY_AUTHORIZED
            - REQUIRES_ACTION
            - PENDING_CAPTURE
            - CAPTURING
            - CAPTURED
            - PARTIALLY_CAPTURED
            - PENDING_SETTLEMENT
            - SETTLED
            - PENDING_CANCELLATION
            - FAILED
            - CANCELLED
            - PENDING_REFUND
            - PARTIALLY_REFUNDED
            - REFUNDED
            - DISPUTED
            - EXPIRED
          description: Status of the payment
          example: PENDING_CAPTURE
        amount:
          type: string
          description: Payment amount in string format
          example: '200.99'
        refundedAmount:
          type: string
          description: Refunded amount in string format
          example: '0.00'
        currency:
          type: string
          description: Three-letter currency code (ISO 4217)
          example: USD
        paymentMethodType:
          type: string
          enum:
            - CARD
            - SPEI
            - CIE_CASH_NET
          description: Type of payment method used
          example: SPEI
        paymentMethodId:
          type: string
          description: CLABE or Card number
        lastFailedEventReason:
          type: string
          nullable: true
          description: Reason for the last failed payment event
          example: Insufficient funds
        lastFailedEventAt:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of the last failed payment event
          example: '2025-05-19T18:14:32.424Z'
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the payment was created
          example: '2025-05-19T18:14:32.424Z'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the payment was last updated
          example: '2025-05-19T18:14:32.523Z'
        billingFirstName:
          type: string
          nullable: true
          description: >-
            Billing first name captured on the payment (included on payment
            order detail when billing details are returned)
        billingLastName:
          type: string
          nullable: true
          description: >-
            Billing last name captured on the payment (included on payment order
            detail when billing details are returned)
        billingPhoneNumber:
          type: string
          nullable: true
          description: Billing phone number
        billingEmail:
          type: string
          format: email
          nullable: true
          description: Billing email address
        billingAddressLine1:
          type: string
          nullable: true
          description: Billing address line 1
        billingAddressLine2:
          type: string
          nullable: true
          description: Billing address line 2
        billingCity:
          type: string
          nullable: true
          description: Billing city
        billingState:
          type: string
          nullable: true
          description: Billing state or province
        billingPostalCode:
          type: string
          nullable: true
          description: Billing postal code
        billingCountry:
          type: string
          nullable: true
          description: Billing country code
        paymentEvents:
          type: array
          description: List of payment events
          items:
            $ref: '#/components/schemas/PaymentEvent'
    PaymentEvent:
      type: object
      required:
        - id
        - action
        - status
        - createdAt
      properties:
        id:
          type: string
          description: Unique identifier for the payment event
          example: evt-123
        action:
          type: string
          description: Action type of the payment event
          example: AUTHORIZATION
        status:
          type: string
          description: Status of the payment event
          example: SUCCESS
        amount:
          type: string
          nullable: true
          description: Amount associated with the event
          example: '100.50'
        currency:
          type: string
          nullable: true
          description: Currency code for the event amount
          example: USD
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the event was created
          example: '2025-05-19T18:14:32.424Z'
        reason:
          type: string
          nullable: true
          description: Reason for the event (e.g., failure reason)
          example: null
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication (required)
    MerchantIdAuth:
      type: apiKey
      in: header
      name: x-merchant-id
      description: Merchant ID for identifying the merchant (required)

````