Construcción de una integración avanzada de Kayana con RYFT en React/Next.js

Crea una integración de pago segura con tarjeta usando Kayana Payment API powered by RYFT en una aplicación Next.js.

Esta guía explica cómo:

• Crear una sesión de pago desde tu backend
• Recuperar la clave pública de RYFT
• Inicializar el SDK de RYFT
• Renderizar el formulario de pago
• Completar el pago de forma segura

Descripción general

La Kayana Payment API te permite aceptar pagos con tarjeta sin necesidad de crear tu propio formulario de pago compatible con PCI.

El flujo de pago funciona así:

1️⃣ El servidor crea una instancia de pago
2️⃣ El servidor recupera la clave pública de RYFT
3️⃣ El frontend carga RYFT SDK
4️⃣ El frontend inicializa la sesión de pago
5️⃣ El cliente ingresa los detalles de la tarjeta y completa el pago

Antes de Comenzar

Necesitarás:

• Kayana Property ID
• API Key
• Acceso a Sandbox Environment
• Conocimientos básicos de Node.js / Next.js

Sandbox vs Producción

Sandbox

Entorno de prueba seguro.

• Utiliza datos de pago de prueba
• Sin transacciones de dinero real
• URL base:

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

Producción

Entorno de pago en vivo.

• Transacciones reales
• Requiere clave API de producción
• URL base:

https://integration.kayana.co.uk

Flujo de Pago RYFT

Frontend carga

https://embedded.ryftpay.com/v2/ryft.min.js

Frontend inicializa RYFT

Ryft.init()

El usuario completa el pago

Ryft.attemptPayment()

Configurar el servidor

URL base

Sandbox:

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

Producción:

https://integration.kayana.co.uk

Paso 1 - Crear instancia de pago (lado del servidor)

Cree una sesión de pago llamando a:

POST /web/payment

Encabezados

Cómo obtener su clave X API

Siga estos pasos en Partner Admin:

• Inicie sesión en Kayana Partner Admin.
• Navegue a Configuración (barra lateral izquierda).
• Seleccione Gestión de clave API.
• Haga clic en Crear clave API.
• Copie la clave generada inmediatamente y envíela en el encabezado.

Parámetros de solicitud

Información de navegador opcional

Dirección de facturación opcional

Ejemplo de implementación de servidor (ruta de API Next.js)

export async function POST() {

try {

const response = await fetch(

"https://integration.dev.kayana.co.uk/web/payment",

{

method: "POST",

headers: {

"Content-Type": "application/json",

"x-api-key": "YOUR_API_KEY",

type: "business",

},

body: JSON.stringify({

property_id: "Prop_039f025cdbc74ca9957dbec1b3e193c1",

psp_code: "RYFT",

currency_code: "GBP",

amount: 100.5,

customer_email: "customer@example.com",

payment_mode: "CARD",

browser_info: {

userAgent: "Mozilla/5.0",

acceptHeader: "*/*",

language: "en-US",

colorDepth: 24,

screenHeight: 1080,

screenWidth: 1920,

timeZoneOffset: 0

},

billing_address: {

street: "221B Baker Street",

city: "London",

postalCode: "NW1 6XE",

country: "GB",

state: "Greater London"

}

}),

}

);

const data = await response.json();

return Response.json(data, { status: response.status });

} catch (error) {

return Response.json(

{ error: "Payment failed", details: error.message },

{ status: 500 }

);

}

}

Ejemplo de respuesta de API

{

"message": "Payment session created successfully",

"status": true,

"data": {

"client_secret": "ps_01KK…MKXJ8NRBCR…",

"next_step": {

"action": "FORM",

"proceed": true

},

"transaction_id": "Tx_9052db2d798f4…..ab8e032",

"order_id": "Order_5ab37f6….0efc5b0a"

}

}

⚠️ Importante

client_secret solo debe usarse en el frontend.

Nunca exponga claves API secretas al navegador.

Paso 2 — Obtener RYFT Public Key

Tu backend debe llamar:

GET /web/payment/public-key

Encabezados

x-api-key

x-psp-code

x-currency-code

type

Ejemplo

export async function GET() {

const response = await fetch(

"https://integration.dev.kayana.co.uk/web/payment/public-key",

{

method: "GET",

headers: {

"x-api-key": "YOUR_API_KEY",

"x-psp-code": "RYFT",

"x-currency-code": "GBP",

"type": "business",

},

}

);

const data = await response.json();

return Response.json(data);

}

RESPUESTA DE EJEMPLO

{

"status": true,

"data": {

"public_key": "pk_sandbox_TlD……d+iMtqu/pmWyGvThg…."

}

}

Paso 3 - Cargar RYFT SDK (Frontend)

Añade el RYFT SDK a tu página.

https://embedded.ryftpay.com/v2/ryft.min.js

Ejemplo usando Next.js:

<Script

src="https://embedded.ryftpay.com/v2/ryft.min.js"

strategy="afterInteractive"

/>

Paso 4 - Inicializar RYFT

Después de obtener:

• publicKey
• clientSecret

Inicializa el SDK.

window.Ryft.init({

publicKey,

clientSecret

});

Paso 5 - Intentar Pago

Desencadenar el pago desde el formulario.

const paymentSession = await window.Ryft.attemptPayment();

Ejemplo:

if (

paymentSession.status === "Approved" ||

paymentSession.status === "Captured"

) {

alert("Payment Successful");

}

Prueba de Pagos

Utiliza tarjetas de prueba RYFT en el entorno de pruebas.

Ejemplo:

Utiliza:

• Cualquier fecha de vencimiento futura
• Cualquier CVC

⚠️ Nunca uses tarjetas de prueba en producción

Errores Comunes

Lista de verificación para pasar a producción

Antes de pasar a producción:

✔ Obtener clave API de producción
✔ Cambiar a URL base de producción
✔ Verificar configuración de RYFT
✔ Probar transacciones con tarjeta real
✔ Implementar webhooks de confirmación de pago

Prácticas de Seguridad Recomendadas

Nunca:

❌ Exponer claves API en el frontend
❌ Usar claves de sandbox en producción
❌ Registrar client_secret públicamente

Siempre:

✔ Procesar pagos a través de rutas de API del servidor

Próximos Pasos

Si prefiere utilizar Stripe como su Proveedor de Servicios de Pago (PSP), Kayana también admite un flujo de integración completo de Stripe. Consulte nuestra guía sobre Crear una integración avanzada de Kayana con Stripe en React/Next.js.