> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear una suscripción

Localpayment permite a los comerciantes configurar suscripciones de pago recurrente con tarjetas de crédito y débito, con soporte tanto para planes fijos como para escenarios de facturación personalizados en varios países. Esta guía describe el proceso para crear una suscripción mediante la API de Localpayment, detallando los parámetros requeridos, el manejo de las respuestas y la interpretación de los códigos de estado.

## Antes de comenzar

Asegúrate de tener:

> [card] [Credenciales de API](https://docs.localpayment.com/es/docs/api-keys-and-environments.md)
>
> Credenciales API válidas y token de acceso para la autenticación.

> [card] [Configuración de la cuenta](https://docs.localpayment.com/es/docs/make-your-first-test-payment.md)
>
> Configuración adecuada de la cuenta para el país de destino y verificación de la empresa.

> [card] [Lista blanca de IP](https://docs.localpayment.com/es/docs/dashboard-whitelist-your-ips.md)
>
> Incluye en la lista blanca las direcciones IP de tus servidores para el acceso a la API.

> [card] [Endpoint del webhook](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Configura una URL de webhook para recibir notificaciones de pago.

***

## Paso 1: Crea una suscripción

Para crear una nueva suscripción, deberás enviar una solicitud `POST` al endpoint [Crear una suscripción](https://docs.localpayment.com/es/reference/create-a-subscription.md).

### Parámetros clave de la solicitud

La solicitud requiere varios parámetros clave, según si estás creando una suscripción de plan fijo o una suscripción personalizada:

| Parámetro | Descripción | Requerido |
| - | - | - |
| `externalId` | Tu referencia única para la suscripción | ✅ |
| `merchant` | Datos del comerciante/negocio | ✅ |
| `country` | Código del país donde se procesará la suscripción | ✅ |
| `currency` | Código de moneda de la suscripción | ✅ |
| `paymentMethod` | Configuración del método de pago | ✅ |
| `planId` | ID de un plan de suscripción predefinido (para planes fijos) | ❌ |
| `autoRecurring` | Frecuencia de facturación | Condicional |
| `amount` | Importe de la suscripción (obligatorio si no hay planId) | Condicional |

### Tipos de suscripción

* **Suscripción de plan fijo**: Úsala cuando tengas planes de suscripción predefinidos creados mediante el endpoint [Crear un plan de suscripción](https://docs.localpayment.com/es/docs/create-a-subscription-plan.md).
* **Suscripción personalizada**: Úsala para escenarios de facturación variable en los que cada pago puede diferir en importe o fecha.

### Códigos de métodos de pago

En todos los países, `paymentMethod.code` identifica el país, la marca de la tarjeta y el producto (crédito o débito), por lo que debes enviar el código que corresponda a la tarjeta y al `country` de la suscripción. En Perú, donde las tarjetas se aceptan en dos monedas, el código también debe coincidir con `currency`: por ejemplo, una tarjeta de crédito Visa usa `6000` con PEN y `6004` con USD. Consulta [Códigos de métodos de pago con tarjeta](https://docs.localpayment.com/es/docs/card-payment-methods.md) para ver los códigos de todos los países.

### Ejemplo de solicitud

A continuación se muestra un ejemplo que utiliza `curl`:

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/payin/subscriptions \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1900",
        "flow": "DIRECT"
    },
    "externalId": "1fe38b94-7e11-44c1-9a88-b4aa9fbe5b4a",
    "country": "COL",
    "amount": 10000.00,
    "currency": "COP",
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "comment": "Test subscription",
    "merchant": {
        "type": "COMPANY",
        "name": "My Company SA DE CV",
        "document": {
            "type": "CC",
            "id": "717321230"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "id": "1073695321",
            "type": "CC"
        },
        "email": "john.doe@example.com"
    },
    "card": {
        "name": "John Doe",
        "number": "4242424242424242",
        "cvv": "123",
        "expirationMonth": "11",
        "expirationYear": "2029",
        "installments": 1
    },
    "type": "SOFTWARE",
    "autoRecurring": {
        "type": "day"
    }
}'
'

```

Consulta todos los [parámetros disponibles](https://docs.localpayment.com/es/reference/create-a-subscription.md) en la solicitud.

***

## Paso 2: Gestionar la respuesta

### Respuesta exitosa

Una respuesta exitosa incluye información detallada de la suscripción e identificadores:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "type": "SOFTWARE",
    "externalId": "1fe38b94-7e11-44c1-9a88-b4aa9fbe5b4a",
    "internalId": "990017f0-7928-4c20-a149-0c1673035f2c",
    "country": "COL",
    "currency": "COP",
    "accountNumber": "{{accountNumber}}",
    "status": {
        "code": "105",
        "description": "WAITINGAUTH",
        "detail": "The subscription is active"
    },
    "date": {
        "creationDate": "2025-11-13T05:05:58.8502173",
        "nextPaymentDate": "2025-11-14T05:05:58.8502036"
    },
    "payments": [
        {
            "externalId": "36e1ce13-8a20-4565-b5f5-e275e1df0010",
            "internalId": "adccc452-4a8c-414c-b777-152f4b0ed2da",
            "status": {
                "code": "100",
                "description": "INPROGRESS",
                "detail": "The payin is pending the confirmation"
            },
            "redirectUrl": "https://web-checkout.stage.localpayment.com/redirect/aHR0cHM6Ly93ZWItY2hlY2tvdXQuc3RhZ2UubG9jYWxwYXltZW50LmNvbS92ZXJpZmljYXRpb24vMDA5Nz9pbnRlcm5hbElkPTQzYzVjZDE1LTg0N2UtNDRhNC05MTU1LTcyYmVmNjZiZDAzMw"
        }
    ],
    "errors": []
}
```

### Campos de respuesta clave

| Parámetro | Descripción | Caso de uso |
| - | - | - |
| `internalId` | Identificador único de suscripción de Localpayment. | Seguimiento y gestión de suscripciones. |
| `status.code` | Código del estado actual de la suscripción. | Monitoreo de estado y automatización. |
| `date.creationDate` | Fecha en que se creó la suscripción | Registro de auditoría e informes. |
| `date.nextPaymentDate` | Fecha en que se procesará el siguiente pago. | Gestión del ciclo de facturación. |
| `payments` | Arreglo de objetos de pago de la suscripción. | Historial de pagos y seguimiento. |

### Respuesta de error

Cuando una solicitud falla, recibirás información detallada sobre el error:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "b27ebf99-e92d-4aca-ba16-f9f8412372cd",
    "internalId": "f95883ce-f08a-485f-9734-0182ec3af70d",
    "country": "COL",
    "currency": "COP",
    "accountNumber": "{{accountNumber}}",
    "type": "SOFTWARE",
    "autoRecurring": {
        "type": "day"
    },
    "status": {
        "code": "300",
        "description": "REJECTED"
    },
    "date": {
        "creationDate": "2025-11-13T05:07:42.7612531"
    },
    "payments": [
        {
            "externalId": "672022a9-b595-4d78-88d0-6ac8d6738082",
            "internalId": "8279db2d-2502-4c1f-8d3b-b668c8b5ff53",
            "status": {
                "code": "300",
                "description": "REJECTED"
            }
        }
    ],
    "errors": [
        {
            "code": "300",
            "detail": "Invalid param + [payer.email] + must not be null"
        }
    ]
}
```

***

## Paso 3: Seguimiento del estado de la transacción

Tras crear una suscripción, supervisa su ciclo de vida mediante estos métodos:

> [card] [Webhooks (recomendado)](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Recibe notificaciones en tiempo real cuando cambie el estado de la transacción. Más eficiente para entornos de producción.

> [card] [Endpoint de la API de estado](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Consulta el estado de las transacciones mediante programación. Útil para sondear o recuperar notificaciones de webhook perdidas.

> [card] [Vista del Business Portal](https://docs.localpayment.com/es/docs/dashboard-overview.md)
>
> Interfaz visual para el seguimiento de transacciones. Ideal para la supervisión manual y el análisis detallado de las transacciones.

### Códigos de estado comunes

La API de Localpayment proporciona varios códigos de estado para indicar el estado de la suscripción.

| Código | Estado | Descripción |
| :- | :- | :- |
| `105` | `ACTIVE` | La suscripción está activa y en curso. |
| `300` | `REJECTED` | Se rechazó la creación de la suscripción o el pago. |

> [!NOTE]
>
> **Referencia completa**
>
> Consulta todos los códigos de estado en nuestra [documentación sobre el estado de las transacciones](https://docs.localpayment.com/es/reference/transaction-status-error-codes).

***

## Probando tu integración

### Escenarios de prueba

Verifica que tu integración gestione estos escenarios:

1. **Creación exitosa de la suscripción**: Flujo estándar de suscripción con una tarjeta válida.
2. **Suscripción de plan fijo**: Suscripción con un plan predefinido.
3. **Suscripción personalizada**: Suscripción con parámetros de facturación personalizados.
4. **Errores de validación**: Tarjeta no válida, faltan campos obligatorios
5. **Actualizaciones de estado**: Gestión de webhooks y sondeo de estado

***

## Próximos pasos

Una vez creada una suscripción, es posible que debas realizar acciones adicionales, como las siguientes:

> [card] [Actualizar suscripción](https://docs.localpayment.com/es/docs/update-a-subscription.md)
>
> Modifica los detalles de una suscripción existente, incluido el importe de facturación, la frecuencia o
> la información del cliente.

> [card] [Cancelar suscripción](https://docs.localpayment.com/es/docs/cancel-a-subscription.md)
>
> Finaliza suscripciones activas conservando el historial de transacciones y
> los registros de facturación.

> [card] [Gestionar webhooks de suscripción](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Configura webhooks para recibir notificaciones en tiempo real sobre los eventos de la suscripción
> y los cambios en el estado de los pagos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.