Crear una Integración Avanzada de Kayana con Stripe en React/Next.js

Crea una integración avanzada de Kayana para recopilar pagos con tarjeta de forma segura utilizando la API de Pagos de Kayana, impulsada por Stripe, para tu tienda de comercio electrónico.

Descripción general

La API de Pagos de Kayana te permite aceptar pagos sin crear tu propio checkout compatible con PCI.

Esta guía te muestra cómo integrar el flujo de Stripe Checkout (Embedded) en modo sandbox.

Lo que crearás:

• Crear una instancia de pago en tu servidor
• Recuperar la clave publicable de Stripe
• Inicializar Stripe en el frontend
• Renderizar la cápsula segura de Checkout de Stripe
• Completar el pago de forma segura

Antes de comenzar

Necesitarás:

• Una ID de propiedad de Kayana
• Acceso al entorno de sandbox
• Conocimientos básicos de desarrollo del lado del servidor
• Node.js / Next.js (se proporcionan ejemplos)

Sandbox vs Producción

Sandbox

• Entorno de prueba seguro
• Utiliza claves de prueba de Stripe
• Sin transacciones reales

Producción

• Requiere un token de autorización
• Utiliza claves de Stripe en vivo
• Procesa pagos reales

Cómo funciona

El flujo de pago de Stripe consta de:

1. Lado del servidor – Crear una instancia de pago
2. Lado del servidor – Recibir:
• client_secret (cs_test_…)
• publishable_key
3. Lado del cliente – Inicializar Stripe y renderizar Embedded Checkout
4. Stripe – Gestiona la confirmación de pago de forma segura

Configurar el servidor

URL base

Sandbox:

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

Production:

https://integration.kayana.co.uk

Paso 1: Crear un Pago

Crea una instancia de pago llamando a:

POST /web/payment

Encabezados

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.

Parámetros de la Solicitud

SOLICITUD DE EJEMPLO

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: "STRIPE", 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();

RESPUESTA DE EJEMPLO

const data = await response.json();

{

"status": true,

"data": {

"instance_id": "Payment_xyz789example",

"client_secret": "cs_test_abc123_secret_xyz456",

"publishable_key": "pk_test_abc123example",

"next_step": {

"action": "FORM",

"proceed": true

},

"transaction_id": "Tx_txn456example"

}

}

Parámetros de Respuesta

Importante: client_secret solo debe usarse en el frontend para inicializar Stripe.

Paso 2: Completar el Pago en Frontend (Stripe Embedded Checkout)

Dado que la API devuelve:

cs_test_…

Esto significa que se ha creado la Sesión de Stripe Checkout.

Debes usar Stripe Embedded Checkout, no confirmCardPayment.

Instalar Stripe SDK

npm install @stripe/react-stripe-js @stripe/stripe-js

Implementación Frontend (Ejemplo Next.js)

"use client";

import { useState } from "react";

import { loadStripe } from "@stripe/stripe-js";

import {

EmbeddedCheckoutProvider,

EmbeddedCheckout,

} from "@stripe/react-stripe-js";

export default function Home() {

const [clientSecret, setClientSecret] = useState(null);

const [stripePromise, setStripePromise] = useState(null);

const createPayment = async () => {

const res = await fetch("/api/business-payment", {

method: "POST",

});

const data = await res.json();

setStripePromise(loadStripe(data.data.publishable_key));

setClientSecret(data.data.client_secret);

};

if (clientSecret && stripePromise) {

return (

<EmbeddedCheckoutProvider

stripe={stripePromise}

options={{ clientSecret }}

>

<EmbeddedCheckout />

</EmbeddedCheckoutProvider>

);

}

return (

<>

<h1>Página de Prueba de Pagos Stripe</h1>

<button onClick={createPayment}>Abrir Cápsula de Pago</button>

</>

);

}

Pruebas en Sandbox

Usa tarjetas de prueba de Stripe:

Detalles Adicionales:

• Vencimiento: Cualquier fecha futura
• CVC: Cualquier 3 dígitos
• ZIP: Cualquier formato válido

Advertencia: Nunca uses tarjetas de prueba en producción.

Manejo de errores

Todas las respuestas incluyen:

{

"status": false,

"message": "Descripción del error"

}

Errores comunes

Lista de verificación para pasar a producción

Antes de la producción:

• Obtener la clave x-api-key de producción
• Cambiar a la URL base de producción
• Usar la clave publicable de Stripe en vivo
• Probar transacciones con tarjetas reales
• Implementar webhooks para confirmación de pago

Nunca:

• Usar claves de sandbox en producción
• Exponer claves secretas en el frontend

Soporte

¿Necesitas ayuda?

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

Próximos pasos

• Explorar la integración de webhooks para notificaciones de pago
• Obtener más información sobre reembolsos y gestión de disputas
• Configurar pagos recurrentes para suscripciones

Próximos Pasos

Si prefieres usar RYFT como tu Proveedor de Servicios de Pago (PSP), Kayana también admite un flujo de integración completo de RYFT. Consulta nuestra guía sobre Crear una integración avanzada de Kayana con RYFT en React/Next.js.