# Suscripciones con página de pago prediseñada

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 pagos recurrentes — no se requiere código de frontend.

## Antes de empezar[​](#antes-de-empezar "Enlace directo al Antes de empezar")

* Necesitas una cuenta de MONEI y tu [clave de API](https://dashboard.monei.com/settings/api) (de prueba o en producción).
* Usa tus [claves de modo de prueba](https://docs.monei.com/es/es/testing/.md) durante el desarrollo.
* Asegúrate de que al menos un [método de pago esté habilitado](https://dashboard.monei.com/settings/payment-methods) en los ajustes de tu cuenta.

## Cómo funciona[​](#cómo-funciona "Enlace directo al 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[​](#pasos-de-integración "Enlace directo al Pasos de integración")

<!-- -->

### 1. Crear una suscripción (lado del servidor)[​](#1-crear-una-suscripción-lado-del-servidor "Enlace directo al 1. Crear una suscripción (lado del servidor)")

Crea una [Suscripción](https://docs.monei.com/es/es/apis/rest/subscriptions-create/.md) en tu servidor con el importe de facturación, la moneda y el intervalo.

* cURL
* Node.js
* PHP
* Python

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)

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;
```

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();

?>
```

server.py

```
import Monei

from Monei import CreateSubscriptionRequest, PaymentCustomer



# 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="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 unidad monetaria más pequeña (p. ej., 1500 = €15,00).
* **currency** cadena — Código de moneda [ISO](https://en.wikipedia.org/wiki/ISO_4217) 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](https://docs.monei.com/es/es/apis/rest/subscriptions-create/.md) disponibles.

### 2. Activar la suscripción (lado del servidor)[​](#2-activar-la-suscripción-lado-del-servidor "Enlace directo al 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
* Node.js
* PHP
* Python

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`)

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;
```

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();

?>
```

server.py

```
from Monei import ActivateSubscriptionRequest



activation = monei.subscriptions.activate(

    "YOUR_SUBSCRIPTION_ID",

    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](https://docs.monei.com/es/es/apis/rest/schemas/payment/.md) para el cobro inicial. Redirige al cliente a `nextAction.redirectUrl`.

Consulta todos los [parámetros de la solicitud](https://docs.monei.com/es/es/apis/rest/subscriptions-activate/.md) disponibles.

### 3. El cliente completa el pago[​](#3-el-cliente-completa-el-pago "Enlace directo al 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[​](#4-el-cliente-es-redirigido-de-vuelta-a-tu-sitio "Enlace directo al 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](https://docs.monei.com/es/es/apis/rest/payments-get/.md) para comprobar el estado del pago inicial, y el endpoint [obtener suscripción](https://docs.monei.com/es/es/apis/rest/subscriptions-get/.md) 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)[​](#5-gestionar-webhooks-lado-del-servidor "Enlace directo al 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](https://docs.monei.com/es/es/apis/rest/schemas/payment/.md) 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](https://docs.monei.com/es/es/apis/rest/schemas/subscription/.md) completo.

Cada solicitud incluye una cabecera `MONEI-Signature`. [Verifica esta firma](https://docs.monei.com/es/es/guides/verify-signature/.md) 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[​](#antes-de-pasar-a-producción "Enlace directo al Antes de pasar a producción")

* Cambia a la clave de API en [modo producción](https://dashboard.monei.com/settings/api).
* Asegúrate de que tus [métodos de pago estén habilitados](https://dashboard.monei.com/settings/payment-methods) 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