Construyendo una integración avanzada de Kayana con RYFT en Python

Crea un flujo de pago usando

Python (FastAPI) y el Ryft SDK

para recopilar de forma segura los detalles de la tarjeta y procesar pagos. Esta guía explica cómo el

complemento de Python (

ryft_plugin.py

) reemplaza la lógica del servidor PHP

mientras mantiene la misma funcionalidad de pago. En lugar de llamar manualmente a todas las APIs de backend, el complemento expone un punto de entrada simplificado:

POST /launch

Este endpoint:

1. Crea una sesión para el pago
2. Abre una página de pago en el navegador
3. Llama internamente a las APIs de la puerta de enlace de pago Kayana
4. Muestra un formulario seguro de pago con tarjeta Ryft

Descripción general

El plugin de Python actúa como un

servidor proxy de pagos

entre la página de pago frontal y la API de pagos de Kayana. En lugar de utilizar solicitudes PHP curl, el plugin utiliza:

• FastAPI para puntos finales de backend
• Python requests library para comunicación de API
• Ryft JavaScript SDK para procesamiento seguro de tarjetas

Esto permite a los desarrolladores ejecutar una pasarela de pagos local mediante Python.

Lo que construirás

El plugin de Python proporciona las siguientes características:

• Iniciar una sesión de checkout
• Crear una instancia de pago utilizando la API de Kayana
• Recuperar la clave pública de Ryft para la inicialización del frontend
• Renderizar una página de checkout segura
• Procesar pagos utilizando el SDK de Ryft
• Registrar sesiones de pago exitosas

Antes de Comenzar

Necesitarás:

• Un Property ID de Kayana
• Una API key de Kayana
• Python 3.10+
• Dependencias instaladas:
• FastAPI
• Uvicorn
• Requests

Configuración del Plugin Python

El plugin define la configuración utilizada para la comunicación de API. CONFIG = { "BASE_URL": "https://integration.dev.kayana.co.uk", "API_KEY": "YOUR_API_KEY" } Estos valores controlan:

• El entorno de API de Kayana
• Encabezados de autenticación
• URLs de punto de conexión de pago

Cómo funciona el complemento de Python

1. El servidor crea una instancia de pago y recibe un client_secret
2. El servidor obtiene la public_key de Ryft
3. El frontend renderiza el formulario de pago y completa la transacción

Paso 1 — Iniciar una sesión de pago

El

punto de entrada del complemento es

/launch

. Este endpoint:

• valida la solicitud
• crea una sesión
• abre la página de pago automáticamente

Endpoint

POST /launch

Cuerpo de la solicitud

Cómo obtener tu clave API X

Sigue estos pasos dentro de Partner Admin:

• Inicia sesión en Kayana Partner Admin.
• Ve a Configuración (barra lateral izquierda).
• Selecciona Gestión de claves API.
• Haz clic en Crear clave API.

Copia la clave generada inmediatamente y envíala en el encabezado.

Solicitud de ejemplo

curl -X POST http://localhost:8000/launch \ -H "Content-Type: application/json" \ -d '{ "property_id": "Prop_abc123example", "amount": 12.0, "currency_code": "GBP", "customer_email": "customer@example.com" }'

Respuesta de ejemplo

{ "launched": true, "session_id": "e3d2f82a-8d9e-4c9b-8d4f-b3a29e82f1aa", "url": "http://localhost:8000/?session_id=e3d2f82a-8d9e-4c9b-8d4f-b3a29e82f1aa", "message": "Navegador abierto con la página de pago." }

Importante: Llamadas internas de API

A diferencia de la guía de integración estándar de Kayana,

el plugin llama automáticamente a las APIs de gateway internamente

.

APIs activadas internamente

Cuando se carga la página de pago, el frontend llama a: POST /proxy/create-payment que internamente llama a: POST /web/payment Esto crea la

instancia de pago

y devuelve el client_secret. A continuación, el plugin recupera la clave de cifrado de Ryft. GET /proxy/public-key que internamente llama a: GET /web/payment/public-key Esto devuelve la

clave pública de PSP

necesaria para inicializar el SDK de Ryft.

Paso 2 — Crear Instancia de Pago (Interno)

Endpoint utilizado internamente por el plugin: POST /proxy/create-payment Esto llama a la API de Kayana: POST /web/payment

Payload de Solicitud

{ "property_id": "Prop_abc123example", "psp_code": "RYFT", "currency_code": "GBP", "amount": 12.0, "customer_email": "customer@example.com" }

Respuesta

{ "status": true, "client_secret": "ps_secret_example" } El client_secret es requerido por el

Ryft SDK para confirmar el pago

.

Paso 3 — Recuperar Clave Pública del PSP (Interna)

Endpoint utilizado internamente: GET /proxy/public-key Llama internamente a: GET /web/payment/public-key

Encabezados Requeridos

Respuesta

{ "status": true, "public_key": "pk_sandbox_abc123examplekey" }

Paso 4 – Renderizar la página de pago

El plugin renderiza dinámicamente la página de checkout usando FastAPI.

Endpoint

GET / La plantilla HTML incluye el SDK de Ryft. <script src="https://embedded.ryftpay.com/v2/ryft.min.js"></script> La página de pago realiza las siguientes acciones:

1. Cargar datos de sesión
2. Crear instancia de pago
3. Recuperar clave pública
4. Inicializar Ryft
5. Habilitar formulario de pago con tarjeta

Paso 5 – Inicializar Ryft SDK

Una vez que se recuperan ambas claves, el frontend inicializa el Ryft SDK. Ryft.init({ publicKey: STATE.publicKey, clientSecret: STATE.clientSecret }); Esto permite que el SDK recopile información de tarjetas de forma segura.

Paso 6 – Registrar Pagos Exitosos

Cuando un pago es exitoso, el plugin registra la sesión de pago.

Endpoint

POST /api/log-payment

Datos de Ejemplo Registrados

ID de Sesión ID de Propiedad Correo Electrónico del Cliente Cantidad Estado de Pago Esto ayuda a rastrear transacciones para depuración o auditoría.

Puntos finales adicionales para pedidos

Flujo sugerido:

Crear pedido → Autorizar pago ↓ [Decisión] ├── Capturar → Éxito ├── Cancelar → Anular pago └── Reembolsar → Después de capturar

Autenticación

Todas las solicitudes de API deben incluir los siguientes encabezados:

1. Capturar pago autorizado

Punto final

POST /web/payment/capture-authorised-payment

Parámetros de solicitud

Ejemplo de cURL

curl --location 'https://integration.dev.kayana.co.uk/web/payment/capture-authorised-payment' \ --header 'Content-Type: application/json' \ --header 'type: business' \ --header 'x-api-key: <YOUR_API_KEY>' \ --data '{ "order_id": "Order_xxx", "amount": 5 }'

Respuesta de ejemplo

{ "status": "success", "message": "Payment captured successfully", "data": { "order_id": "Order_xxx", "captured_amount": 5 } }

2. Cancelar pago autorizado

Punto final

POST /web/payment/cancel-authorised-payment

Parámetros de solicitud

Ejemplo de cURL

curl --location 'https://integration.dev.kayana.co.uk/web/payment/cancel-authorised-payment?order_id=Order_xxx' \ --header 'Content-Type: application/json' \ --header 'type: business' \ --header 'x-api-key: <YOUR_API_KEY>'

Respuesta de ejemplo

{ "status": "success", "message": "Payment cancelled successfully" }

3. Reembolsar pago

Punto final

POST /web/payment/refund

Parámetros de solicitud

Ejemplo de cURL

curl --location --request POST 'https://integration.dev.kayana.co.uk/web/payment/refund?order_id=Order_xxx&amount=0.4' \ --header 'Content-Type: application/json' \ --header 'type: business' \ --header 'x-api-key: <YOUR_API_KEY>'

Respuesta de ejemplo

{ "status": "success", "message": "Refund processed", "data": { "order_id": "Order_xxx", "refunded_amount": 0.4 } }

4. Obtener detalles del pedido

Punto final

GET /web/order/fetch-order-details-by-order-id

Parámetros de solicitud

Ejemplo de cURL

curl --location 'https://integration.dev.kayana.co.uk/web/order/fetch-order-details-by-order-id?order_id=Order_xxx' \ --header 'type: business' \ --header 'x-api-key: <YOUR_API_KEY>'

Respuesta de ejemplo

{ "status": "success", "data": { "order_id": "Order_xxx", "status": "captured", "amount": 5 } }

Manejo de Errores

El plugin incluye un sistema avanzado de clasificación de errores. Los errores se categorizan en:

• Token de autorización inválido
• Encabezados faltantes
• ID de propiedad inválido
• Moneda no compatible
• Configuración de PSP faltante

Ejemplo de lógica de clasificación: _classify_error(data, status_code) Cada error devuelve: error_code message solution Esto proporciona retroalimentación clara a los desarrolladores.

Prueba del Plugin

Ejecuta el servidor usando:

• uvicorn main:app --reload --port 8000

El servidor FastAPI se iniciará en:

• http://localhost:8000

La documentación de la API está disponible en:

• http://localhost:8000/docs

Tarjetas de Prueba en Sandbox

Puede probar pagos utilizando tarjetas sandbox de Ryft. Cree una Checkout Page con Kaya…

Pasar a Producción

Antes de pasar a producción:

1. Reemplaza la clave API de sandbox
2. Actualiza la URL base
3. Usa claves públicas de producción
4. Desactiva tarjetas de prueba
5. Asegura las credenciales de API

Nunca expongas claves de producción en código del lado del cliente.

Soporte

¿Necesitas ayuda?

• Problemas técnicos: Contacta al Soporte Técnico de Kayana
• Credenciales de producción: Solicita a tu gestor de cuenta de Kayana
• Configuración de PSP: Ponte en contacto con el Soporte Técnico de Kayana

¿Qué sigue?

• Explora la integración de webhooks para notificaciones de pago
• Aprende sobre reembolsos y gestión de disputas
• Configura pagos recurrentes para suscripciones

Próximos Pasos

Si prefieres usar Stripe como tu Proveedor de Servicios de Pago (PSP), Kayana también admite un flujo de integración completo con Stripe. Consulta nuestra guía sobre Construcción de una Página de Pago con el Plugin Stripe de Kayana (Python).