--- updatedAt: 2026-10-08T22:06:01.000Z agentTools: projectIndex: https://docs.ventipay.com/llms.txt --- # Reglas y errores Las reglas que la API aplica en el servidor y los códigos de error que puede devolver el flujo de cobro. # Reglas y errores ## Reglas del producto Estas reglas se aplican siempre en el servidor y no son configurables: * **El `amount` de un checkout se calcula en el servidor** a partir de sus ítems, descuentos e impuestos. No puedes fijarlo directamente ni editarlo después. * **Solo un checkout `unpaid` puede pagarse, cancelarse o recibir cupones.** Un checkout pagado solo admite reembolsos. * **Un checkout `unpaid` expira automáticamente** al pasar `expires_at` (por defecto, 2 semanas). * **La captura de un pago autorizado vence a los 10 minutos** de la autorización. Después, solo puede cancelarse. * **Solo se reembolsan pagos capturados y no disputados**, hasta agotar el monto original. El destino es el medio de pago original o la billetera Venti del cliente. * **Un reembolso en vivo exige balance disponible suficiente** (y ningún balance negativo) en tu cuenta Venti. * **Las comisiones de la venta no se devuelven al reembolsar**, salvo que tu comercio tenga contratado el reembolso de comisiones. * **Los checkouts de estado de cuenta de Cuentas Venti no son reembolsables** ([ver Cuentas Venti](https://docs.ventipay.com/docs/accounts)). * **Los medios de pago disponibles los define la configuración de tu comercio**: un intento con un medio deshabilitado se rechaza en el servidor. * **El `promotion_code` de un cupón es único por comercio** (por modo live/test) y se normaliza a mayúsculas alfanuméricas. * **Un cupón se aplica una sola vez por checkout**, debe estar activo, vigente y aplicable a checkouts, y respeta sus restricciones de monto mínimo, tope por aplicación y tope acumulado. * **Un cupón `amount_off` solo aplica en su misma moneda**; uno `percent_off` descuenta entre 0 y 100% con piso del total en 0. * **Un botón de pago inactivo no genera checkouts.** ## Códigos de error Errores del tipo `invalid_request_error` que puede devolver el flujo de Pagos: | Código | Cuándo | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | `invalid_checkout_status` | Intento de pagar un checkout que no está `unpaid`. | | `payment_not_cancelable` | Cancelación de un checkout que no está `unpaid`, o de un pago que no está `requires_capture`. | | `payment_not_authorizable` | Autorización de un pago que no está `requires_authorization`, o cupón aplicado a un checkout que no está `unpaid`. | | `payment_not_capturable` | Captura fuera de la ventana de 10 minutos o de un pago no capturable (reembolsado, disputado, ya capturado). | | `payment_not_refundable` | Reembolso de un pago no capturado, disputado o sin cargo exitoso. | | `already_refunded` | El pago ya no tiene monto disponible para reembolsar. | | `invalid_amount` | Monto de reembolso negativo o mayor al disponible. | | `insufficient_balance` | Balance insuficiente (o negativo) para cubrir el reembolso. | | `invalid_refund_destination` | Destino de reembolso distinto de `payment_method` o `customer_balance`. | | `refund_amount_must_be_greater_than_zero` | Monto de reembolso menor que cero a nivel de cargo. | | `invalid_charge_currency` | Inconsistencia entre la moneda del pago y la de su cargo exitoso. | | `financial_account_repayment_checkout_forbidden` | Intento de reembolsar un checkout de estado de cuenta. | | `fashions_park_not_refundable` | El medio de pago tarjeta Fashion's Park no admite reembolsos por API. | | `invalid_payment` | El checkout no tiene un objeto exitoso reembolsable. | | `invalid_loan` | El loan asociado al checkout no existe o no es válido. | | `invalid_merchant` | El comercio está deshabilitado. | | `invalid_payment_method` | Falta el medio de pago al iniciar la autorización. | | `invalid_payment_method_config` | El medio de pago elegido no está habilitado para tu comercio. | | `invalid_installment_name` | El programa de cuotas solicitado no existe. | | `customer_not_found` | El `customer_id` indicado no existe. | | `risk_fraud` | La creación del cobro fue bloqueada por señales de fraude. | | `invalid_coupon` | El código no existe, está inactivo, expiró o no aplica a este checkout (moneda, monto mínimo, `applies_to`). | | `coupon_in_use` | El cupón ya fue aplicado a este checkout. | | `coupon_reached_maximum_amount` | El cupón alcanzó su tope acumulado de uso (`restrictions.maximum_usage_amount`). | | `invalid_currency` | Cupón `amount_off` sin moneda válida. | | `invalid_percent` | Cupón `percent_off` con porcentaje fuera de 0–100. | | `invalid_payment_button` | El botón de pago no tiene moneda o comercio válidos. | | `invalid_payment_amount` | El botón de pago no tiene un monto válido. | | `payment_button_inactive` | El botón de pago está inactivo. | Los errores siguen el formato estándar de la API: ```json { "error": { "type": "invalid_request_error", "code": "insufficient_balance", "message": "El balance disponible no es suficiente." } } ``` ## Límites actuales * Los checkouts no se eliminan: usa `canceled` / `expired` como estados terminales. * Un checkout se paga con **un solo medio de pago**: el pago dividido no está soportado. * El reembolso hacia `merchant_balance` que aparece en el objeto `Refund` es de uso interno de Venti; por API solo puedes reembolsar a `payment_method` o `customer_balance`. * `duration` y `duration_cycles` de los cupones solo tienen efecto en [suscripciones](https://docs.ventipay.com/docs/subscriptions); en checkouts el descuento es siempre único. * Las monedas soportadas para cobrar son las publicadas en [monedas](https://docs.ventipay.com/docs/currency).