Pagos y estados
Una factura describe un pedido. Un pago es un intento específico de pagarlo. Un intento de pago y la disponibilidad de su enlace son estados separados.
En esta página
El registro de pago#
La factura almacena los términos del pedido; el pago identifica su operación de pasarela. El primer lanzamiento reserva un vínculo duradero y una clave de idempotencia del servidor. Una vez que comienza el envío, otro método no puede crear un segundo cargo en la misma factura.
GET /api/payment-links y GET /api/v1/payments devuelven link.payment al propietario. El estado activo/pausado/cancelado/expirado del enlace es independiente del estado del pago. Un cliente solo puede leer su operación mediante el token aleatorio de pago.
| Datos | Propósito |
|---|---|
| Identificador y pedido | Asociar el intento con una compra |
| Monto base y moneda | La base de cálculo |
| Método de pago | Comisión e impuesto aplicables |
| Contribuyente de IVA | Quién cubre el impuesto |
| Comisión, IVA y totales | Cálculo guardado |
| Estado y hora | Estado actual de la transacción |
| Referencia del evento de la pasarela | Fuente de confirmación del servidor |
Estados de operación en vivo#
La demo utiliza registros de prueba separados. Cambiar un estado de demo no confirma un pago real ni modifica registros financieros.
| Estado | Significado |
|---|---|
| pendiente | Operación creada; en espera de acción o resultado |
| requires_action | Se requiere un código bancario o confirmación del cliente |
| processing | El proveedor aún está confirmando el resultado |
| exitoso | El servidor verificó el pago exacto |
| fallido | El intento terminó sin pago confirmado |
| expired | Instrucciones vencidas; la conciliación sigue disponible |
| review_required | Se requiere revisión adicional; no pague de nuevo |
| partially_paid | Solo se recibió parte del monto; no cree otro pago |
| partially_refunded | Parte del pago fue reembolsada |
| refunded | Reembolso confirmado |
| disputed | La operación está en disputa |
La fuente de verdad#
Un webhook firmado activa una lectura autenticada de la operación exacta de la pasarela. Se validan los IDs, el pedido, la moneda, el método, los montos base y final, el modo en vivo y la versión monotónica. El nombre de un evento entrante por sí solo no es prueba de dinero.
El estado, el recibo y el evento del comerciante se consolidan atómicamente. Las respuestas antiguas no pueden sobrescribir una versión más nueva; los duplicados no se cumplen dos veces y un estado pendiente no puede reemplazar un pago confirmado. Estos registros no crean automáticamente un saldo retirable ni un pago.
Cuando el resultado es desconocido#
- 1
Conserve la factura original y el identificador de la operación.
- 2
Lea GET /api/checkout/{token}/status; no crea un cargo.
- 3
Use POST /api/checkout/{token}/reconcile cuando se necesite una conciliación explícita.
- 4
No cambie el método, el monto ni la clave de idempotencia después de un resultado incierto.
Múltiples tiendas y un precio base en USD#
Elija Todas las tiendas para análisis y operaciones agregados, o seleccione una tienda para sus propios registros. Cada tienda tiene un storeId, nombre, IVA predeterminado, facturas, claves de API, endpoints de webhook, historial de eventos y aplicación web separados. Las notificaciones y tickets de soporte pertenecen a la cuenta. Una cuenta puede crear hasta 100 tiendas. Los registros existentes permanecen en su primera tienda.
Las facturas del nuevo espacio de trabajo usan pricingMode="universal" y un precio base en USD. Any incluye tarjeta, alipay, sbp y cripto; un comerciante puede seleccionar un subconjunto. Tarjetas y Alipay cobran en USD. SBP cobra en RUB usando el tipo de referencia USD/RUB del Banco de Rusia. Cripto cobra USDT bajo la regla explícita de factura 1 USD = 1 USDT. Esta es una regla de conversión de factura, no una cotización de mercado de USDT. La pasarela proporciona la tasa de la moneda seleccionada, el monto exacto de transferencia y las instrucciones antes de la transferencia.
El tipo de referencia y ambos montos se congelan al crear. Las facturas que implican conversión de RUB vencen dentro de 24 horas. Si no se puede obtener el tipo de referencia, la creación falla con FX_UNAVAILABLE; no se usa ningún tipo de respaldo inventado o desactualizado. El monto en minor del propietario y las cotizaciones usan la moneda contable USD. quotes[method].settlement contiene la cotización de cargo nativa. El checkout público expone la moneda de cargo seleccionada en currency, el precio original en baseAmountMinor/baseCurrency y el tipo de referencia en fx. Una vez que un pago ha sido despachado, su método no se puede cambiar; una factura tiene una operación de pasarela.
Cree una clave de API dentro de la tienda prevista y envíe Authorization: Bearer <key> desde su servidor. Su vinculación a tienda es inmutable; X-Kevmi-Store no puede otorgarle acceso a otra tienda. Las sesiones del navegador seleccionan X-Kevmi-Store: <storeId>; omitirlo selecciona la primera tienda. El valor all solo es aceptado por GET /api/account/dashboard y GET /api/payment-links. Las mutaciones requieren una tienda seleccionada, Origin y X-CSRF-Token. Los IDs de cuenta y los IDs de tienda son identificadores diferentes.
Por compatibilidad, las solicitudes de API sin pricingMode="universal" conservan el precio nativo y las restricciones de moneda originales. Las facturas existentes nunca se recalculan. Los recibos confirmados en análisis reflejan pagos verificados menos gastos de factura guardados; no son un saldo retirable. Las monedas de factura heredadas permanecen separadas y los pagos se gestionan con soporte. Cumpla un pedido solo después de verificar payment.fulfillmentReady=true y payment.status="succeeded" a través de la API del servidor, el historial de eventos o un webhook firmado.