Construir una Integración Avanzada de Kayana con Stripe en Node.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 construir tu propio checkout compatible con PCI.

Esta guía te acompaña a través de la integración del flujo de Stripe Embedded Checkout usando Node.js en modo sandbox.

Lo que construirás

En esta guía harás lo siguiente:

1. Crear una instancia de pago en tu servidor Node.js
2. Recuperar la clave publicable de Stripe
3. Inicializar Stripe en el frontend
4. Renderizar la cápsula Embedded Checkout segura de Stripe
5. Completar el pago de forma segura

Antes de comenzar

Necesitarás:

• Un ID de propiedad de Kayana
• Acceso al entorno de prueba
• Conocimientos básicos de Node.js
• Un servidor backend de Node.js
• Un frontend de React / Next.js

Sandbox vs Producción

Sandbox

Entorno de prueba seguro

• Utiliza claves de prueba de Stripe
• Sin transacciones reales
• Ideal para desarrollo y pruebas

Producción

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

Cómo Funciona

El flujo de pago de Stripe consta de:

Lado del servidor (Node.js)

Crea una instancia de pago utilizando la API de Kayana.

El servidor recibe

• client_secret
• publishable_key

Lado del cliente

Inicializa Stripe y renderiza Embedded Checkout

Stripe

Maneja la confirmación de pago de forma segura.

Configuración del servidor (Node.js)

URL base

Sandbox:

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

Paso 1 - Crear un Pago (Backend Node.js)

Crea un endpoint de API Node.js que llame a la API de pagos de Kayana.

Ejemplo usando Express.js.

Instalar dependencias

npm install express node-fetch dotenv

Implementación del Servidor Node.js

require("dotenv").config();

const express = require("express");

const fetch = require("node-fetch");

const app = express();

app.use(express.json());

app.post("/api/business-payment", async (req, res) => {

try {

const response = await fetch(

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

{

method: "POST",

headers: {

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

"x-api-key": process.env.KAYANA_API_KEY,

type: "business",

},

body: JSON.stringify({

property_id: "Prop_abc123example",

psp_code: "STRIPE",

currency_code: "GBP",

amount: 12.0,

customer_email: "customer@example.com",

}),

}

);

const data = await response.json();

res.json(data);

} catch (error) {

res.status(500).json({

status: false,

message: "Error en la creación del pago",

});

}

});

app.listen(3001, () => {

console.log("Servidor ejecutándose en el puerto 3001");

});

Variables de Entorno

Crea un archivo .env:

KAYANA_API_KEY=YOUR_API_KEY

⚠️ Nunca expongas esta clave en el frontend.

Parámetros de solicitud

Ejemplo de respuesta de API

{

"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 debe usarse solo en el frontend para inicializar Stripe.

Paso 2 - Integración Frontend (Stripe Embedded Checkout)

Instalar Stripe SDK:

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

Implementación Frontend de React / 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 PaymentPage() {

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

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

const createPayment = async () => {

const res = await fetch("http://your-server.com/api/business-payment", {

method: "POST",

});

const data = await res.json();

if (data.status) {

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

setClientSecret(data.data.client_secret);

} else {

alert(data.message);

}

};

if (clientSecret && stripePromise) {

return (

<EmbeddedCheckoutProvider

stripe={stripePromise}

options={{ clientSecret }}

>

<EmbeddedCheckout />

</EmbeddedCheckoutProvider>

);

}

return (

<>

<h1>Página de Prueba de Pago con Stripe</h1>

<button onClick={createPayment}>

Abrir Cápsula de Pago

</button>

</>

);

}

Flujo de Pago

El usuario hace clic en "Pagar"

↓

El frontend llama a la API de Node.js

↓

Node.js llama a la API de Kayana

↓

Kayana crea una sesión de Stripe Checkout

↓

Devuelve:

client_secret

publishable_key

↓

El frontend carga Stripe

↓

Aparece Stripe Embedded Checkout

↓

El usuario ingresa los detalles de la tarjeta

↓

Stripe confirma el pago

Pruebas en Sandbox

Utiliza tarjetas de prueba de Stripe.

Detalles adicionales:

• Fecha de vencimiento → Cualquier fecha futura
• CVC → Cualquier 3 dígitos
• ZIP → Cualquier formato válido

⚠️ Nunca utilices tarjetas de prueba en producción.

Manejo de Errores

Todas las respuestas incluyen:

{

"status": false,

"message": "Description of error"

}

Errores Comunes

Lista de verificación para puesta en marcha

Antes de producción:

• Obtener production x-api-key
• Cambiar a production base URL
• Usar live Stripe publishable key
• Probar transacciones con tarjetas reales
• Implementar Stripe webhooks

Nunca:

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

Soporte

Soporte técnico: Equipo técnico de Kayana Credenciales de producción: Contacte con su gestor de cuentas de Kayana.