> ## 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. # Refund a Payment of a payment order (v2) > Refunds one of the Payments under a payment order. For legacy single-Payment orders (`allowPartials=false`), `paymentId` is optional and the sole Payment is refunded. For split-tender orders (`allowPartials=true`), `paymentId` is required — the caller must say which Payment to refund. The action does NOT update the order's `status` directly: the orchestrator consumer recomputes the aggregate status from the resulting PaymentEvent. After a full refund of every Payment, the order transitions to REFUNDED (terminal). After a partial refund, it transitions back to PARTIALLY_PAID and accepts new Payments via the addPayment endpoint. This is an internal endpoint. ## OpenAPI ````yaml /api-reference/orchestrator-openapi.json post /v2/payment-orders/{id}/refund 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}/refund: post: tags: - Payment Order summary: Refund a Payment of a payment order (v2) description: >- Refunds one of the Payments under a payment order. For legacy single-Payment orders (`allowPartials=false`), `paymentId` is optional and the sole Payment is refunded. For split-tender orders (`allowPartials=true`), `paymentId` is required — the caller must say which Payment to refund. The action does NOT update the order's `status` directly: the orchestrator consumer recomputes the aggregate status from the resulting PaymentEvent. After a full refund of every Payment, the order transitions to REFUNDED (terminal). After a partial refund, it transitions back to PARTIALLY_PAID and accepts new Payments via the addPayment 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: type: object required: - amount properties: amount: type: number minimum: 0 exclusiveMinimum: true description: >- Refund amount in minor currency units (centavos): 5000 = $50.00 MXN. Must be a positive integer. Bounded per Payment by module-payment (cannot exceed that Payment's remaining capturable amount). Note: unlike the legacy v1 refund endpoint, which takes major units, v2 takes minor units. example: 1000 reason: type: string description: >- Optional free-text reason. Persisted on the order's `refundReason` field for auditing. example: customer requested paymentId: type: string format: uuid description: >- Which Payment of the order to refund. Required when the order has `allowPartials=true`. For non-partial orders this can be omitted and the lone Payment is used. example: a0b0c9d4-6ce9-40e4-873a-e234c1d93639 responses: '200': description: >- Refund accepted by module-payment. The response is a snapshot of the resulting Payment-level refund — the order's aggregate status is materialized asynchronously by the consumer. content: application/json: schema: type: object properties: id: type: string format: uuid description: Refund event id status: type: string example: COMPLETED amount: type: string description: Amount of THIS refund (smallest currency unit) example: '100000' refundedAmount: type: string description: >- Cumulative refunded amount of the targeted Payment after this call example: '100000' paymentMethodType: type: string example: CARD createdAt: type: string format: date-time updatedAt: type: string format: date-time '400': description: Validation failed — invalid amount, invalid paymentId format, etc. content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '404': description: Payment order or its Payments not found content: application/json: schema: $ref: '#/components/schemas/NotFoundError' '422': description: >- Operation rejected by a business rule (missing paymentId on split-tender order, paymentId doesn't belong to order, downstream module-payment state error like 'Payment is not in the correct state to be refunded'). content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - INVALID_OPERATION message: type: string details: type: object additionalProperties: true examples: missingPaymentId: summary: Split-tender order requires paymentId value: error: code: INVALID_OPERATION message: paymentId is required to refund a partial-payments order details: paymentOrderId: f5b58a6b-204b-4be9-8b4b-58c5fe87e869 allowPartials: true availablePaymentIds: - a0b0c9d4-6ce9-40e4-873a-e234c1d93639 - 20912eee-6047-40c7-97b4-48501bb36ef4 paymentNotInOrder: summary: Provided paymentId does not belong to the order value: error: code: INVALID_OPERATION message: >- Payment 11111111-1111-1111-1111-111111111111 does not belong to payment order f5b58a6b-204b-4be9-8b4b-58c5fe87e869 downstreamStateError: summary: >- module-payment rejected the refund (e.g., Cybersource PENDING settlement) value: error: code: INVALID_OPERATION message: >- Payment is not in the correct state to be refunded: a0b0c9d4-6ce9-40e4-873a-e234c1d93639 details: paymentOrderId: f5b58a6b-204b-4be9-8b4b-58c5fe87e869 paymentId: a0b0c9d4-6ce9-40e4-873a-e234c1d93639 downstreamStatus: 500 '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalError' components: schemas: 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 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) ````