Suscripciones con la página de pago alojada

Redirige a los clientes a una página de pago alojada por MONEI para activar su suscripción. Esta es la forma más sencilla de comenzar a cobrar — no se requiere código de frontend.

Antes de empezar

• Necesitas una cuenta de MONEI y tu clave de API (de prueba o en producción).
• Usa tus claves de modo de prueba durante el desarrollo.
• Asegúrate de que al menos un método de pago esté habilitado en los ajustes de tu cuenta.

Tu clave API está en MONEI Dashboard → Configuración → Acceso a API:

Página Acceso a API en los ajustes del panel de MONEI, con tu ID de cuenta y tu clave API

Cómo funciona

1. Tu backend crea una suscripción con el importe, la moneda y el intervalo de facturación
2. La suscripción se activa, devolviendo una redirectUrl para el pago inicial
3. El cliente es redirigido a la página de pago alojada por MONEI
4. El cliente completa el pago inicial (incluyendo 3D Secure si es necesario)
5. Tras el pago, el cliente es redirigido de vuelta a tu completeUrl
6. MONEI envía webhooks tanto para el pago inicial como para los cambios de estado de la suscripción — los pagos recurrentes se cobran automáticamente en cada intervalo de facturación

Pasos de integración

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

Crea una Suscripción en tu servidor con el importe de facturación, la moneda y el intervalo.

cURL

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"
}'

(Reemplaza YOUR_API_KEY con tu clave de API real de MONEI)

Node.js

server.js

import {Monei} from '@monei-js/node-sdk';

// Replace YOUR_API_KEY with your actual MONEI API key
const monei = new Monei('YOUR_API_KEY');

const subscription = await monei.subscriptions.create({
  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'
});

// You will need the subscription id in the next step
const subscriptionId = subscription.id;

PHP

server.php

<?php
require_once 'vendor/autoload.php';

use Monei\MoneiClient;
use Monei\Model\CreateSubscriptionRequest;
use Monei\Model\PaymentCustomer;

// Replace YOUR_API_KEY with your actual MONEI API key
$monei = new MoneiClient('YOUR_API_KEY');

$subscription = $monei->subscriptions->create(
  new CreateSubscriptionRequest([
    'amount' => 1500,
    'currency' => 'EUR',
    'interval' => 'month',
    'interval_count' => 1,
    'description' => 'Pro Plan Monthly',
    'customer' => new PaymentCustomer([
      'name' => 'John Doe',
      'email' => 'john.doe@example.com'
    ]),
    'callback_url' => 'https://example.com/subscriptions/callback',
    'payment_callback_url' => 'https://example.com/payments/callback'
  ])
);

// You will need the subscription id in the next step
$subscriptionId = $subscription->getId();
?>

Python

server.py

import Monei
from Monei import CreateSubscriptionRequest, PaymentCustomer, SubscriptionInterval

# Replace YOUR_API_KEY with your actual MONEI API key
monei = Monei.MoneiClient(api_key="YOUR_API_KEY")

subscription = monei.subscriptions.create(
    CreateSubscriptionRequest(
        amount=1500,
        currency="EUR",
        interval=SubscriptionInterval("month"),
        interval_count=1,
        description="Pro Plan Monthly",
        customer=PaymentCustomer(
            name="John Doe",
            email="john.doe@example.com"
        ),
        callback_url="https://example.com/subscriptions/callback",
        payment_callback_url="https://example.com/payments/callback"
    )
)

# You will need the subscription id in the next step
subscription_id = subscription.id

Parámetros clave:

• amount entero positivo — Importe en la (p. ej., 1500 = €15,00).
• currency cadena — Código de moneda ISO de tres letras (p. ej., EUR).
• interval cadena — Intervalo de facturación: day, week, month o year.
• intervalCount número — Número de intervalos entre cada cobro (p. ej., 3 con month = trimestral).
• callbackUrl cadena — URL que recibe los webhooks de cambio de estado de la suscripción.
• paymentCallbackUrl cadena — URL que recibe los webhooks de pago de cada cobro recurrente.

Consulta todos los parámetros de la solicitud disponibles.

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

Activa la suscripción para iniciar el proceso de facturación. La respuesta incluye una redirectUrl para enviar al cliente a la página de pago alojada por MONEI.

cURL

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"
}'

(Reemplaza YOUR_SUBSCRIPTION_ID y YOUR_API_KEY)

Node.js

server.js

const activation = await monei.subscriptions.activate('YOUR_SUBSCRIPTION_ID', {
  completeUrl: 'https://example.com/checkout/complete'
});

// Redirect the customer to this URL
const redirectUrl = activation.nextAction.redirectUrl;

PHP

server.php

<?php
use Monei\Model\ActivateSubscriptionRequest;

$activation = $monei->subscriptions->activate(
  'YOUR_SUBSCRIPTION_ID',
  new ActivateSubscriptionRequest([
    'complete_url' => 'https://example.com/checkout/complete'
  ])
);

// Redirect the customer to this URL
$redirectUrl = $activation->getNextAction()->getRedirectUrl();
?>

Python

server.py

from Monei import ActivateSubscriptionRequest

activation = monei.subscriptions.activate(
    "YOUR_SUBSCRIPTION_ID",
    activate_subscription_request=ActivateSubscriptionRequest(
        complete_url="https://example.com/checkout/complete"
    )
)

# Redirect the customer to this URL
redirect_url = activation.next_action.redirect_url

La respuesta de activación es un objeto Payment para el cobro inicial. Redirige al cliente a nextAction.redirectUrl.

Consulta todos los parámetros de la solicitud disponibles.

3. El cliente completa el pago

El cliente introduce sus datos de pago en la página de pago alojada por MONEI y completa cualquier verificación 3D Secure requerida.

4. El cliente es redirigido de vuelta a tu sitio

El cliente es redirigido a completeUrl con los parámetros de consulta payment_id y subscription_id.

Usa el endpoint obtener pago para comprobar el estado del pago inicial, y el endpoint obtener suscripción para verificar el estado de la suscripción (debería ser ACTIVE o TRIALING).

nota

No confíes únicamente en la redirección para confirmar el pago — utiliza siempre el webhook (siguiente paso) como fuente de verdad autorizada.

5. Gestionar webhooks (lado del servidor)

MONEI envía dos tipos de notificaciones de webhook:

• Callback de pago — enviado a paymentCallbackUrl para el pago inicial y cada cobro recurrente. El cuerpo de la solicitud contiene el objeto Payment completo.
• Callback de suscripción — enviado a callbackUrl cuando cambia el estado de la suscripción (p. ej., PENDING → ACTIVE). El cuerpo de la solicitud contiene el objeto Subscription completo.

Cada solicitud incluye una cabecera MONEI-Signature. Verifica esta firma para confirmar que la solicitud proviene de MONEI, y devuelve un código de estado HTTP 200 para confirmar la recepción.

Si MONEI no recibe una respuesta 200, la notificación se reintentará.

Antes de pasar a producción

• Cambia a la clave de API 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