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

# Charge a pending payment order

> Processes payment for an existing payment order that was created with `pending: true`. This is the second step of the two-step payment flow. The order must be in PENDING status. Provide the payment method and optional billing/device information to process the charge. The persist flag on payment methods is not supported for this endpoint. This is an internal endpoint.



## OpenAPI

````yaml /api-reference/orchestrator-openapi.json post /v2/payment-orders/{id}/charge
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}/charge:
    post:
      tags:
        - Payment Order
      summary: Charge a pending payment order
      description: >-
        Processes payment for an existing payment order that was created with
        `pending: true`. This is the second step of the two-step payment flow.
        The order must be in PENDING status. Provide the payment method and
        optional billing/device information to process the charge. The persist
        flag on payment methods is not supported for this endpoint. This is an
        internal endpoint.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Payment order ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargePaymentOrderRequest'
      responses:
        '200':
          description: Payment order charged successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentOrderResponse'
        '400':
          description: >-
            Validation failed - missing required fields, invalid payment method,
            or order is not in PENDING status
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - type: object
                    properties:
                      message:
                        type: string
                        example: x-merchant-id header is required
              examples:
                missingHeader:
                  summary: Missing required header
                  value:
                    message: x-merchant-id header is required
                persistNotSupported:
                  summary: Persist flag not allowed
                  value:
                    message: persist is not supported when charging a pending order
                speiNotEnabled:
                  summary: SPEI payment method not enabled
                  value:
                    message: SPEI payment method is not enabled for merchant
                cieCashNetNotEnabled:
                  summary: CIE Cash Net payment method not enabled
                  value:
                    message: CIE Cash Net payment method is not enabled for merchant
                virtualTerminalNotEnabled:
                  summary: Virtual Terminal not enabled
                  value:
                    message: Virtual Terminal is not enabled for this merchant
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Payment order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
components:
  schemas:
    ChargePaymentOrderRequest:
      type: object
      required:
        - paymentMethod
      description: >-
        Request body for charging a pending payment order. The persist flag is
        not supported when charging a pending order.
      properties:
        paymentMethod:
          oneOf:
            - type: object
              required:
                - type
                - cardDetails
              properties:
                type:
                  type: string
                  enum:
                    - card
                  description: Payment method type
                cardDetails:
                  type: object
                  required:
                    - number
                    - expiryMonth
                    - expiryYear
                    - cvc
                  properties:
                    number:
                      type: string
                      minLength: 1
                      description: Card number
                      example: '4111111111111111'
                    expiryMonth:
                      type: string
                      minLength: 2
                      maxLength: 2
                      pattern: ^(0[1-9]|1[0-2])$
                      description: Two-digit expiry month (01-12)
                      example: '12'
                    expiryYear:
                      type: string
                      minLength: 2
                      maxLength: 2
                      description: Two-digit expiry year
                      example: '25'
                    cvc:
                      type: string
                      minLength: 1
                      description: Card CVC/CVV
                      example: '123'
            - type: object
              required:
                - type
                - paymentMethodId
              properties:
                type:
                  type: string
                  enum:
                    - payment_method_id
                  description: Use existing payment method
                paymentMethodId:
                  type: string
                  minLength: 1
                  description: ID of the saved payment method
                  example: pm_123456789
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - spei
                  description: SPEI transfer payment method
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - cie_cash_net
                  description: >-
                    CIE Cash Net payment method for cash payments at convenience
                    stores
        billingAddress:
          type: object
          description: Billing address (required when paymentMethod.type is 'card')
          properties:
            address:
              type: string
              description: Street address
              example: 123 Main St
            city:
              type: string
              description: City name
              example: Mexico City
            state:
              type: string
              description: State or province
              example: CDMX
            postalCode:
              type: string
              description: Postal or ZIP code
              example: '01000'
            country:
              type: string
              pattern: ^[A-Z]{2}$
              description: Two-letter country code (ISO 3166-1 alpha-2)
              example: MX
        deviceInformation:
          $ref: '#/components/schemas/DeviceInformation'
        isVirtualTerminal:
          type: boolean
          default: false
          description: >-
            Whether the payment originates from a Virtual Terminal. When true,
            the 3DS flow is skipped in the Decision Manager.
      example:
        paymentMethod:
          type: card
          cardDetails:
            number: '4111111111111111'
            expiryMonth: '12'
            expiryYear: '25'
            cvc: '123'
        billingAddress:
          address: Av. Reforma 123
          city: Mexico City
          state: CDMX
          postalCode: '01000'
          country: MX
    CreatePaymentOrderResponse:
      type: object
      required:
        - id
        - amount
        - currency
        - status
      properties:
        id:
          type: string
          format: uuid
          description: Payment order unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        externalMerchantReference:
          type: string
          description: External merchant reference ID
          example: ORDER-12345
        amount:
          type: number
          description: >-
            Total amount charged to the customer (subtotalAmount +
            surchargeAmount).
          example: 257.5
        subtotalAmount:
          type: number
          description: >-
            Merchandise subtotal — the amount agreed before any surcharge.
            Immutable after order creation.
          example: 250
        surchargeAmount:
          type: number
          nullable: true
          description: >-
            Surcharge applied on top of subtotalAmount. Null when no surcharge
            applies.
          example: 7.5
        surchargeRate:
          type: number
          nullable: true
          description: >-
            Snapshot of the merchant's surcharge rate (percent) at charge time.
            Null when no surcharge applies.
          example: 3
        orderNumber:
          type: string
          description: System-generated order number
          example: C25123101
        currency:
          type: string
          description: Currency code
          example: MXN
        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
          example: PENDING
        description:
          type: string
          description: Payment order description
          example: 'Payment for order #12345'
        metadata:
          type: object
          nullable: true
          description: Arbitrary JSON metadata stored with the payment order
          additionalProperties: true
          example:
            orderId: ORD-123
            source: web
        dueDate:
          type: string
          format: date-time
          nullable: true
          description: Due date for the payment order
          example: '2026-04-15T00:00:00.000Z'
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
          example: '2025-10-20T10:00:00.000Z'
        paymentMethod:
          type: object
          properties:
            type:
              type: string
              description: Payment method type
              example: card
            id:
              type: string
              description: Payment method ID (if persisted)
              example: pm_123456789
            cardDetails:
              type: object
              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
                expiryMonth:
                  type: string
                  description: Card expiry month
                  example: '12'
                expiryYear:
                  type: string
                  description: Card expiry year
                  example: '25'
            speiDetails:
              type: object
              description: SPEI details (present when payment method type is 'spei')
              properties:
                clabe:
                  type: string
                  description: CLABE account number for SPEI transfer (18 digits)
                  example: '123456789012345678'
            cieDetails:
              type: object
              description: >-
                CIE Cash Net details (present when payment method type is
                'cie_cash_net')
              properties:
                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'
            paycashDetails:
              type: object
              description: >-
                PayCash details (present when payment method type is 'paycash').
                The reference is generated by the external PayCash API and used
                by the payer to deposit cash at affiliated convenience stores.
              properties:
                reference:
                  type: string
                  description: PayCash reference for cash payment at affiliated stores
                  example: '9318500000999888777'
        allowPartials:
          type: boolean
          description: >-
            Echoes the `allowPartials` flag from creation. When true, the order
            accepts additional Payments via the addPayment endpoint until it is
            fully covered.
          example: true
        amountPaid:
          type: number
          description: >-
            Cumulative sum of captured amounts on this order. On split-tender
            orders that get partially refunded and re-paid, this can grow beyond
            `amount` because it is a historical ledger; use `amountPending` (or
            compute `amountPaid - amountRefunded`) to know the live balance.
          example: 200
        amountPending:
          type: number
          description: >-
            Outstanding amount left to cover, derived as `max(0, amount -
            (amountPaid - amountRefunded))`. Reaches 0 when the order is fully
            paid net of refunds.
          example: 50
        amountRefunded:
          type: number
          description: >-
            Cumulative sum of refunded amounts across the order's Payments. Like
            `amountPaid`, this is a historical ledger and is bounded per Payment
            by module-payment.
          example: 50
        payment:
          type: object
          description: >-
            The Payment that triggered this response (the one just created for
            the addPayment / charge call, or the original Payment for a regular
            create).
          properties:
            id:
              type: string
              format: uuid
              example: a0b0c9d4-6ce9-40e4-873a-e234c1d93639
            amount:
              type: string
              example: '1000'
            status:
              type: string
              description: Payment status as reported by module-payment.
              example: CAPTURED
            paymentMethodType:
              type: string
              example: CARD
        payments:
          type: array
          description: >-
            All Payments associated with this order, ordered by creation time
            (oldest first), including the one in the `payment` field. Useful for
            split-tender clients that need to enumerate every Payment.
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              amount:
                type: string
              status:
                type: string
              paymentMethodType:
                type: string
              createdAt:
                type: string
                format: date-time
        customer:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: Customer ID
              example: 123e4567-e89b-12d3-a456-426614174000
            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
              example: john.doe@example.com
            phoneNumber:
              type: string
              description: Customer's phone number
              example: '+525512345678'
        payerAuthentication:
          type: object
          description: 3DS authentication details (when required)
          properties:
            id:
              type: string
              description: Authentication session ID
            url:
              type: string
              format: uri-reference
              description: 3DS authentication URL
            jwt:
              type: string
              description: JWT token for authentication
            stepUpUrl:
              type: string
              format: uri-reference
              description: Step-up authentication URL
            accessToken:
              type: string
              description: Access token for authentication
      example:
        id: 123e4567-e89b-12d3-a456-426614174000
        externalMerchantReference: ORDER-12345
        amount: 250
        orderNumber: C25123101
        currency: MXN
        status: PENDING
        description: 'Payment for order #12345'
        metadata:
          orderId: ORD-123
          source: web
        createdAt: '2025-10-20T10:00:00.000Z'
        paymentMethod:
          type: card
          cardDetails:
            last4: '1111'
            brand: VISA
            country: US
            expiryMonth: '12'
            expiryYear: '25'
        customer:
          id: 123e4567-e89b-12d3-a456-426614174000
          firstName: John
          lastName: Doe
          email: john.doe@example.com
          phoneNumber: '+525512345678'
    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
    DeviceInformation:
      type: object
      description: Device and browser information for fraud detection
      properties:
        ipAddress:
          type: string
          description: IP address of the device
          example: 192.168.1.1
        userAgent:
          type: string
          description: User agent string
          example: Mozilla/5.0...
        userAgentBrowserValue:
          type: string
          description: Browser type from user agent
        httpAcceptBrowserValue:
          type: string
          description: HTTP Accept header value
        httpAcceptContent:
          type: string
          description: HTTP Accept-Content header value
        fingerprintSessionId:
          type: string
          description: Fingerprint session identifier
        httpBrowserColorDepth:
          type: string
          description: Browser color depth
          example: '24'
        httpBrowserJavaEnabled:
          type: boolean
          description: Whether Java is enabled in browser
        httpBrowserJavaScriptEnabled:
          type: boolean
          description: Whether JavaScript is enabled in browser
        httpBrowserLanguage:
          type: string
          description: Browser language
          example: en-US
        httpBrowserScreenHeight:
          type: string
          description: Browser screen height in pixels
          example: '1080'
        httpBrowserScreenWidth:
          type: string
          description: Browser screen width in pixels
          example: '1920'
        httpBrowserTimeDifference:
          type: string
          description: Browser time difference from UTC in minutes
        hostName:
          type: string
          description: Hostname of the device
        cookiesAccepted:
          type: string
          description: Whether cookies are accepted
        httpBrowserEmail:
          type: string
          description: Email from browser settings
  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)

````