Integración de la pasarela de pago
La pasarela procesa las operaciones financieras. Kevmi las conecta con pedidos, ajustes de tienda y notificaciones. Esta guía describe el contrato de integración y las verificaciones de disponibilidad.
En esta página
Verificación de disponibilidad#
Kevmi utiliza la API v3 de la pasarela para crear y recuperar operaciones, leer estados y conciliar resultados. La integración admite transporte cifrado de tarjeta y códigos bancarios, pagos QR de Alipay y SBP, un catálogo de criptomonedas/redes y eventos financieros entrantes.
gateway.configured en GET /api/config informa si están presentes los ajustes de conexión requeridos. Este endpoint no sondea la pasarela; gateway.connected=false aquí significa que la conectividad no se ha verificado. Para una factura específica, lea invoice.availability en GET /api/checkout/{token}: verifica el método, el monto, los términos y la aprobación del comerciante. El campo de compatibilidad invoice.gatewayConnected refleja availability.available y tampoco es una verificación de salud ni una garantía de aprobación del pago.
Un nuevo pago e intento de tarjeta requieren que la última solicitud de revisión web del comerciante esté aprobada. La aprobación por sí sola no conecta la pasarela de pago. Si la revisión cambia después del envío, la operación existente permanece disponible para lecturas de estado, conciliación y un código bancario solicitado.
Contrato de pago del cliente#
Los datos sensibles se cifran en el navegador con RSA-OAEP-256 y A256GCM. La clave privada permanece en la pasarela. Kevmi valida que la intención pertenece a esta factura y propósito, transmite el sobre, y no almacena números de tarjeta en texto plano, CVV, nombre del comprador, correo electrónico, códigos bancarios ni el sobre mismo.
Instale la extensión de transporte cifrado en el host de la pasarela antes de habilitar tarjetas. Verifica la firma de la intención, expiración, reproducción, orden y montos. No hay alternativa en texto plano. Esto describe el mecanismo de protección, no la certificación PCI.
| Ruta de Kevmi | Propósito |
|---|---|
| GET /api/checkout/{token} | Factura, cotización, disponibilidad del método y pago existente |
| POST /api/checkout/{token}/card-intent | Intención de un solo uso y clave pública para pago o código |
| POST /api/checkout/{token}/pay | Iniciar una operación; la tarjeta usa sellado: {intent,jwe} |
| POST /api/checkout/{token}/code | Código de un solo uso cifrado para el desafío bancario actual |
| GET /api/checkout/{token}/status | Leer la operación original sin otro cargo |
| POST /api/checkout/{token}/reconcile | Reconciliar explícitamente la operación original |
| GET /api/checkout/{token}/crypto-services | Monedas, redes y límites actuales para una factura USDT |
Alojamiento y conectividad de pasarela#
Kevmi admite alojamiento en Sites en Cloudflare Workers con D1, y autoalojamiento en Node.js con SQLite. SQLite requiere un volumen persistente y copias de seguridad. La pasarela de pago se ejecuta como un servicio separado con su propio almacenamiento duradero.
Una pasarela externa requiere un origen HTTPS alcanzable por el servidor. En el paquete autoalojado, el servidor se conecta a un servicio de pasarela fijo en la red privada del contenedor; la API del servicio de pasarela no está expuesta a internet. El sitio público y las devoluciones de llamada usan HTTPS. El navegador también cifra los datos de la tarjeta y los códigos bancarios antes de que lleguen a Kevmi.
localhost se refiere al servidor o contenedor actual; no expone la computadora del propietario de la pasarela. Las claves de conexión y los secretos pertenecen solo a la configuración del servidor.
Para un dominio personalizado, establezca un origen HTTPS público en NEXT_PUBLIC_SITE_URL antes de compilar. La documentación, los enlaces canónicos y los recursos de indexación usan este valor. Acepta solo un esquema y un host con un puerto opcional, sin ruta, consulta, fragmento ni credenciales. Emparejelo con APP_ORIGIN en la configuración del servidor.
Cálculo y términos admitidos#
Las facturas del nuevo espacio de trabajo usan un precio base en USD y Any ofrece los cuatro métodos. SBP convierte a RUB al tipo de referencia congelado del Banco de Rusia; cripto usa la regla explícita de factura 1:1 USD/USDT. El precio nativo heredado sigue disponible para facturas antiguas y solicitudes de API sin pricingMode=universal. Consulte la sección de múltiples tiendas y precios en USD a continuación.
Para un pago nuevo en vivo con tarjeta o Alipay, la pasarela actual solo admite feeCustomerPercent=0 y vatCustomerPercent=100: el comerciante cubre toda la comisión de procesamiento y el IVA se añade completo para el cliente. Otras participaciones se pueden guardar y calcular en una factura, pero la ejecución está bloqueada con unsupported_allocation. El servidor nunca cambia silenciosamente los términos guardados. Los pagos cripto SBP y USDT admiten todas las participaciones de comisión de procesamiento y no tienen IVA.
Enviar un total_cents arbitrario no cambia el cálculo de impuestos del proveedor. Un monto real que difiera del total guardado entra en revisión y no puede confirmar el cumplimiento. Los campos business_balance de la pasarela se conservan como evidencia de liquidación, no se tratan como un saldo de comerciante de Kevmi.
Conectar una pasarela en vivo#
Conectar la pasarela incluye la configuración del servidor, verificaciones de los canales seleccionados y el procesamiento de eventos financieros verificados. La disponibilidad de la configuración se verifica por separado de la conectividad del proveedor. Un pago exitoso se acepta después de verificar el estado y el monto de la operación. Las instrucciones de implementación están en ops/gateway-integration.md.
- 1
Implemente el servidor de Kevmi y la pasarela como servicios separados. Configure almacenamiento duradero, copias de seguridad y los procesos en segundo plano requeridos.
- 2
Para una conexión externa, establezca un origen HTTPS en GATEWAY_BASE_URL. El paquete autoalojado usa su servicio interno configurado. Ambos requieren un GATEWAY_API_KEY solo de servidor y un GATEWAY_WEBHOOK_SECRET separado; los secretos nunca llegan al navegador.
- 3
Establezca el BACKEND_WEBHOOK_URL de la pasarela en /api/gateway/webhook en Kevmi y un BACKEND_WEBHOOK_SECRET coincidente.
- 4
Habilite el transporte cifrado de tarjetas y mantenga su clave privada exclusivamente en el host de la pasarela. Verifique la disponibilidad de la clave pública y los ajustes de firma de intenciones coincidentes.
- 5
Verifique la disponibilidad de los canales, las restricciones y la aprobación del sitio del comerciante antes del lanzamiento.
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.