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

# Soft delete a payment order

> Soft deletes a payment order, identified by its unique ID or external ID. Only orders in PENDING, FAILED, EXPIRED, or CANCELLED status can be deleted; otherwise a 422 is returned. Deletion is terminal and cannot be undone. The operation is idempotent: deleting an already-deleted order returns the order unchanged. An optional reason can be provided in the request body.



## OpenAPI

````yaml /api-reference/orchestrator-openapi.json delete /v2/payment-orders/{id}
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/{id}:
    delete:
      tags:
        - Payment Order
      summary: Soft delete a payment order
      description: >-
        Soft deletes a payment order, identified by its unique ID or external
        ID. Only orders in PENDING, FAILED, EXPIRED, or CANCELLED status can be
        deleted; otherwise a 422 is returned. Deletion is terminal and cannot be
        undone. The operation is idempotent: deleting an already-deleted order
        returns the order unchanged. An optional reason can be provided in the
        request body.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
          description: Payment order unique identifier or external ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  maxLength: 255
                  description: >-
                    Optional reason for deleting the payment order. Trimmed
                    before validation; must not exceed 255 characters.
      responses:
        '200':
          description: Payment order soft deleted successfully (or was already deleted)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentOrderResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Payment order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '422':
          description: >-
            Payment order cannot be deleted in its current status. Only PENDING,
            FAILED, EXPIRED, and CANCELLED orders are deletable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
        '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
    NotFoundError:
      type: object
      description: Not found error response
      properties:
        message:
          type: string
          description: Error message
          example: Merchant not found
      example:
        message: Merchant not found
    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)

````