Construcción de una Integración Kayana Avanzada en PHP

Crea una integración avanzada de Kayana en formulario PHP para recopilar detalles de tarjeta de forma segura y aceptar pagos usando la API de Pagos de Kayana, impulsada por RYFT, para tu tienda de comercio electrónico.

Descripción general

La API de Pagos de Kayana te permite aceptar pagos de clientes sin necesidad de construir tu propio proceso de pago. Esta guía te lleva a través de la integración del flujo de pagos en modo sandbox, donde puedes probar de forma segura sin procesar transacciones reales.

Lo que construirás:

• Crear una instancia de pago en tu servidor
• Recuperar la clave pública del PSP para la inicialización del frontend
• Mostrar un formulario de pago seguro usando el SDK de RYFT
• Procesar el pago de forma segura

Antes de comenzar

Necesitarás:

• Un ID de propiedad de Kayana
• Acceso al entorno sandbox
• Conocimientos básicos de desarrollo del lado del servidor (se proporcionan ejemplos en PHP)

Sandbox vs Producción:

• Sandbox: Entorno de prueba con transacciones falsas – no se requiere autenticación
• Producción: Entorno en vivo – requiere un token de autorización de Kayana

Cómo funciona

El flujo de pago consta de tres pasos:

1. Lado del servidor: Crear una instancia de pago y recibir un client_secret
2. Lado del servidor: Obtener la clave pública de PSP para la inicialización del frontend
3. Lado del cliente: Renderizar el formulario de pago usando el SDK de RYFT y completar la transacción

Configurar el servidor

URL base

Sandbox:

https://integration.dev.kayana.co.uk

Producción:

https://integration.kayana.co.uk

Autenticación

Todas las solicitudes de API de producción requieren un encabezado de autorización con tu token de API.

x-api-key: YOUR_API_KEY

Nota: En modo sandbox, la autenticación es opcional pero se puede incluir para probar solicitudes compatibles con producción.

Paso 1: Crear un pago

Crea una instancia de pago llamando al endpoint /admin/payment. Esto devuelve un client_secret que usarás para completar el pago en el frontend.

Endpoint

POST /web/payment

Encabezados

Parámetros de solicitud

Solicitud de ejemplo

<?php $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => 'https://integration.dev.kayana.co.uk/web/payment', CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => json_encode([ "property_id" => "Prop_abc123example", 'psp_code' => $config['stripe']['psp_code'], "currency" => "GBP", "amount" => 12.0, "customer_email" => "customer@example.com" ]), CURLOPT_HTTPHEADER => array( 'Content-Type: application/json', 'x-api-key: YOUR_API_KEY' ), )); $response = curl_exec($curl); curl_close($curl); $data = json_decode($response, true); echo $response; ?>

Respuesta

{ "status": true, "data": { "instance_id": "Payment_xyz789example", "client_secret": "ps_secret123example", "next_step": { "action": "FORM", "proceed": true }, "transaction_id": "Tx_txn456example" } }

Parámetros de respuesta

Importante: El client_secret es información sensible y debe mantenerse segura. Solo pásalo a tu frontend cuando sea necesario para completar el pago.

Paso 2: Recuperar la clave pública del PSP

Obtén la clave pública requerida para inicializar el SDK de pago de RYFT en tu frontend. Esta clave es específica para tu PSP (RYFT) y la moneda asociada.

Endpoint

GET /web/payment/public-key

Encabezados

Solicitud de ejemplo

<?php $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => 'https://integration.dev.kayana.co.uk/web/payment/public-key', CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => array( 'x-api-key: YOUR_API_KEY', 'x-psp-code: RYFT', 'x-currency-code: GBP' ), )); $response = curl_exec($curl); curl_close($curl); $data = json_decode($response, true); echo $response; ?>

Respuesta

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

Parámetros de respuesta

Paso 3: Completar el pago en el frontend

Utiliza la clave pública para inicializar el SDK de RYFT y el client secret para confirmar el pago.

Descripción general de la integración

1. Incluye el SDK de RYFT en tu frontend
2. Inicializa RYFT con tu public_key
3. Crea un formulario de pago utilizando los componentes de interfaz de usuario de RYFT
4. Confirma el pago utilizando el client_secret

Nota: La implementación exacta del frontend depende del SDK de JavaScript de RYFT. Consulta la documentación de RYFT para obtener pasos detallados de integración del frontend.

Flujo básico del frontend

// Initialize RYFT with the public key const ryft = Ryft('pk_sandbox_abc123examplekey'); // Create a payment form const elements = ryft.elements(); const cardElement = elements.create('card'); cardElement.mount('#card-element'); // Handle form submission const form = document.getElementById('payment-form'); form.addEventListener('submit', async (event) => { event.preventDefault(); // Confirm payment with client_secret const {error, paymentIntent} = await ryft.confirmCardPayment( 'ps_secret123example', // client_secret from Step 1 { payment_method: { card: cardElement } } ); if (error) { console.error(error.message); } else { console.log('Payment successful!', paymentIntent); } });

Pruebas en sandbox

Utiliza estos números de tarjeta de prueba para simular diferentes escenarios de pago en el entorno sandbox. Estas tarjetas no procesan transacciones reales.

Números de tarjeta de prueba

Detalles adicionales de tarjetas de prueba:

• Fecha de vencimiento: Cualquier fecha futura (p. ej., 12/34)
• CVC: Cualquier 3 dígitos (p. ej., 123)
• Código postal: Cualquier formato válido (p. ej., SW1A 1AA)

Advertencia: Las tarjetas de prueba de sandbox nunca deben usarse en producción. Los detalles de tarjetas reales solo deben ingresarse en el entorno de producción.

Puntos finales adicionales para pedidos

Flujo sugerido:

Crear pedido → Autorizar pago

↓

[Decisión]

├── Capturar → Éxito

├── Cancelar → Anular pago

└── Reembolso → Después de capturar

Autenticación

Todas las solicitudes de API deben incluir los siguientes encabezados:

1. Capturar Pago Autorizado

Endpoint

POST /web/payment/capture-authorised-payment

Parámetros de Solicitud

Ejemplo 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

Endpoint

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. Reembolso de Pago

Endpoint

POST /web/payment/refund

Parámetros de Solicitud

Ejemplo 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

Endpoint

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

Todas las respuestas de la API incluyen un campo de estado que indica éxito o fallo.

Formato de respuesta de error

{ "status": false, "message": "Description of what went wrong" }

Errores comunes

Pasar a producción

Antes de pasar a producción:

1. Obtén credenciales de producción: Contacta al Soporte Técnico de Kayana para obtener tu token de autorización de producción
2. Actualiza tu URL base: Cambia de la URL de sandbox a la URL de producción
3. Añade autenticación: Incluye tu token de autorización en todas las solicitudes
4. Actualiza las claves del frontend: Reemplaza las claves públicas de sandbox con claves de producción
5. Elimina tarjetas de prueba: Asegúrate de que solo se acepten métodos de pago reales

Necesario: Nunca uses claves de sandbox o tarjetas de prueba en un entorno de producción. Las claves de producción deben mantenerse seguras y nunca exponerse 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 cuentas de Kayana
• Configuración de PSP: Ponte en contacto con el Soporte Técnico de Kayana
• Explora la integración de webhooks para notificaciones de pago
• Aprende sobre reembolsos y manejo de disputas
• Configura pagos recurrentes para suscripciones

Próximos pasos:

Si prefieres Stripe como tu proveedor de servicios de pago, consulta nuestra guía sobre

cómo crear una integración avanzada de Kayana para RYFT en PHP

.