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).
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:

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance"
  }
}

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; en checkouts el descuento es siempre único.
Las monedas soportadas para cobrar son las publicadas en monedas.