Saltar al contenido principal

Suscripciones con checkout personalizado

Recoge los datos de pago directamente en tu sitio usando MONEI Components para activar suscripciones. Esto te da control total sobre la experiencia de checkout.

Antes de empezar​

Elige tu flujo​

Hay dos formas de activar una suscripción con MONEI Components:

Token primeroActivar primero
Cómo funcionaRecoger datos de pago → generar token → activar con tokenActivar → obtener ID de pago → recoger datos → confirmar pago
Cuándo usarloFlujo más sencillo, menos peticiones al servidorCuando necesitas el objeto de pago antes de recoger los datos
Init del componenteaccountId + sessionIdpaymentId

Token primero (recomendado)​

Genera un token de pago en el cliente y luego activa la suscripción en el servidor con ese token.

1. Crear una suscripción (lado del servidor)​

Crea una Suscripción en tu servidor. Este paso es idéntico al flujo de la página de pago prediseñada.

POST https://api.monei.com/v1/subscriptions
curl --request POST 'https://api.monei.com/v1/subscriptions' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 1500,
  "currency": "EUR",
  "interval": "month",
  "intervalCount": 1,
  "description": "Pro Plan Monthly",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "callbackUrl": "https://example.com/subscriptions/callback",
  "paymentCallbackUrl": "https://example.com/payments/callback"
}'

2. Añadir el componente a tu página (lado del cliente)​

Incluye monei.js en tu página de checkout y monta el componente CardInput usando tu accountId y un sessionId único.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.monei.com/v3/monei.js"></script>
</head>
<body>
  <div id="card-element">
    <!-- MONEI Card Input Component will be inserted here -->
  </div>
  <button id="subscribe-button">Subscribe</button>
  <script src="client.js"></script>
</body>
client.js
// Initialize CardInput with your accountId and a unique sessionId
const cardElement = monei.CardInput({
  accountId: 'YOUR_ACCOUNT_ID',
  sessionId: 'unique_session_id' // Unique per customer session
});

// Render the Component into the container
cardElement.render('#card-element');
important

Usa un sessionId diferente para cada sesión de cliente. Esto garantiza que el cliente que genera el token coincide con el cliente que paga. Debes pasar el mismo sessionId al activar la suscripción en el paso 4.

3. Obtener el token de pago (lado del cliente)​

Cuando el cliente hace clic en el botón de suscripción, envía el input de tarjeta para generar un paymentToken de un solo uso.

client.js
document.getElementById('subscribe-button').addEventListener('click', async () => {
  // Generate a payment token from the card input
  const {token, error} = await cardElement.submit();

  if (error) {
    // Show the error to the customer
    console.error('Error:', error);
    return;
  }

  // Send the token and sessionId to your server
  const response = await fetch('/activate-subscription', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
      subscriptionId: '{{subscription_id}}',
      paymentToken: token,
      sessionId: 'unique_session_id'
    })
  });

  const result = await response.json();
  // Handle the result (e.g., show success message)
});

4. Activar con token (lado del servidor)​

Activa la suscripción con el paymentToken y el sessionId recibidos del cliente.

POST https://api.monei.com/v1/subscriptions/{id}/activate
curl --request POST 'https://api.monei.com/v1/subscriptions/YOUR_SUBSCRIPTION_ID/activate' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "paymentToken": "token_from_client",
  "sessionId": "unique_session_id"
}'

5. Gestionar webhooks (lado del servidor)​

La gestión de webhooks es la misma que en el flujo de la página de pago prediseñada. MONEI envía callbacks de pago a paymentCallbackUrl y los cambios de estado de la suscripción a callbackUrl. Siempre verifica la firma y devuelve un código de estado 200.

Activar primero (alternativa)​

Activa la suscripción primero para obtener un ID de pago, luego recoge los datos de pago y confirma desde el cliente.

1. Crear una suscripción​

Igual que el paso 1 anterior.

2. Activar la suscripción (lado del servidor)​

Activa sin paymentToken — la respuesta es un objeto Payment con un payment.id.

POST https://api.monei.com/v1/subscriptions/{id}/activate
curl --request POST 'https://api.monei.com/v1/subscriptions/YOUR_SUBSCRIPTION_ID/activate' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "completeUrl": "https://example.com/checkout/complete"
}'
important

Usa el payment.id de la respuesta para inicializar el componente CardInput — no redirijas al cliente a nextAction.redirectUrl. Esa URL es para el flujo de la página de pago prediseñada.

3. Montar el componente y confirmar el pago (lado del cliente)​

Inicializa el CardInput con el paymentId de la respuesta de activación y luego confirma el pago.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.monei.com/v3/monei.js"></script>
</head>
<body>
  <div id="card-element"></div>
  <button id="subscribe-button">Subscribe</button>
  <script src="client.js"></script>
</body>
client.js
// Initialize CardInput with the paymentId from the activation response
const paymentId = '{{payment_id}}'; // Passed from your server
const cardElement = monei.CardInput({paymentId: paymentId});
cardElement.render('#card-element');

document.getElementById('subscribe-button').addEventListener('click', async () => {
  const {token, error} = await cardElement.submit();

  if (error) {
    console.error('Error:', error);
    return;
  }

  // Confirm the payment with the generated token
  const result = await monei.confirmPayment({
    paymentId: paymentId,
    paymentToken: token
  });

  // Show the result to the customer
  // Always rely on webhooks for the definitive payment status
  console.log('Payment status:', result.status);
});

4. Gestionar webhooks​

Igual que en el flujo token primero — MONEI envía webhooks tanto para los pagos como para los cambios de estado de la suscripción.

Antes de pasar a producción​

  • Cambia a la clave de API y al Account ID en modo producción.
  • Asegúrate de que tus métodos de pago estén habilitados en modo producción.
  • Comprueba que tus endpoints de webhook gestionan correctamente tanto los callbacks de pago como los de suscripción.
Límites del modo de prueba

En modo de prueba, las suscripciones tienen los siguientes límites:

  • Máximo 3 suscripciones activas por cuenta
  • Las suscripciones se cancelan automáticamente tras 12 pagos
  • Los intervalos de facturación por minuto y hora están disponibles para pruebas más rápidas