Suscripciones

Las Suscripciones te permite vincular clientes a tus planes existentes. Con esta API, podrás integrar un sistema de suscripciones en tu plataforma, facilitando la inscripción, renovación y cancelación de clientes en distintos planes de suscripción.

Ciclo de vida de una suscripción

El siguiente diagrama ilustra los diferentes estados por los que puede pasar una suscripción y las transiciones entre ellos, basadas en eventos como pagos exitosos, fallidos o acciones administrativas.

#	Acción	Transición
1	Se creó una suscripción con éxito.	`Inicio` → `Activa`
2	Ejecución de pago recurrente exitoso.	`Activa`/`Pendiente` → `Activa`
3	El administrador bloqueó la suscripción.	`Activa` → `Bloqueada`
4	El administrador desbloqueó la suscripción.	`Bloqueada` → `Activa`
5	El comprador desactivó su suscripción.	`Activa` → `Inactiva`
6	Error en pago recurrente (diario/semanal) - intentos `=` 1.	`Activa` → `Inactiva`
7	El link de suscripción no es válido (caducado, inactivo o eliminado).	`Activa`/`Bloqueada`/`Pendiente` → `Inactiva`
8	Error en pago recurrente (mensual/anual) - intentos `<=` 2.	`Activa` → `Pendiente`
9	Error en pago recurrente (mensual/anual) - intentos `=` 3.	`Pendiente` → `Inactiva`
10	Error al crear una suscripción.	`Inicio` → `Error`

Funcionalidades

Autenticación y Seguridad

Para acceder a la API, es necesario autenticar cada petición mediante un token, consulta Autenticación.

📌 Creación de suscripciones para un cliente a un plan específico.

URL base: https://api-sandbox.n1co.shop
Método: POST
Endpoint: /api/v3/Subscriptions
Descripción: Crear suscripción.
Cabeceras necesarias:
Content-Type: application/json
Authorization: Bearer {your_token}
Ejemplo:

Request
Response

{
    "planId": 1544,
    "customer": {
        "id": "Customer001",
        "name": "Carlos Dúran",
        "email": "[email protected]",
        "phoneNumber": "+50364331900"
    },
    "paymentMethod": {
        "id": "689f93049b36afba505e7bc8"
    },
    "backupPaymentMethod": {
        "id": "689f69319b36afba505e7bc0"
    },
    "authenticationId": null,
    "billingInfo": {
        "countryCode": "string",
        "stateCode": "string",
        "zipCode": "string"
    },
    "locationCode": "N1C0CD001"
}

{
    "status": "SUCCEEDED",
    "message": "El pago fue realizado exitosamente",
    "error": null,
    "authentication": null,
    "subscription": {
        "subscriptionId": 481,
        "planId": 1544,
        "name": "Plan ePay",
        "description": "Descripción de la suscripción ePay",
        "created": "2025-10-24T21:22:47.7452894Z",
        "amount": 45.9900,
        "amountFormatted": "$45.99",
        "billingCycle": 1,
        "billingCycleType": "Mes",
        "currencyCode": "USD",
        "locale": "es-SV",
        "currentPeriodStart": "2025-10-24T21:22:47.4571820Z",
        "currentPeriodEnd": "2025-10-25T21:22:47.4571820Z",
        "timezone": "America/El_Salvador",
        "subscriptionStatus": "Activa",
        "customer": {
            "name": "Carlos Dúran",
            "email": "[email protected]",
            "phone": "+50364331900",
            "paymentMethodName": "TEST 001",
            "paymentMethodCardBrand": "visa",
            "paymentMethodBin": "400000",
            "paymentMethodLastDigits": "2701",
            "backupPaymentMethodName": "TEST 002",
            "backupPaymentMethodCardBrand": "visa",
            "backupPaymentMethodBin": "424242",
            "backupPaymentMethodLastDigits": "4242"
        }
    },
    "payment": {
        "chargeId": "676a97bb-f19e-4311-aac7-b9c6911c3a1d",
        "authorizationCode": "831000"
    }
}

Crear métodos de pago

Necesitarás de datos de tarjetas de pruebas →, esta documentación te guía a través de escenarios de prueba válidas para el ambiente sandbox.

Antes de realizar un cobro, debes crear un método de pago →. Luego de crear el método de pago se debe usar el ID en el campo paymentMethod→id (Requerido) o el campo backupPaymentMethod→id (Opcional), estos deben ser distintos.

- Parámetros de la petición

Parámetro	Tipo	Requerido	Descripción
`planId`	integer	✅	ID del plan de suscripción
`customer`	object	✅	Información del cliente
`customer.id`	string	❌	Identificador único del cliente
`customer.name`	string	✅	Nombre completo del cliente
`customer.email`	string	✅	Email del cliente
`customer.phoneNumber`	string	❌	Número de teléfono con código de país
`paymentMethod`	object	✅	Método de pago principal
`paymentMethod.id`	string	✅	ID del token devuelto en la tokenización
`backupPaymentMethod`	object	❌	Método de pago de respaldo
`backupPaymentMethod.id`	string	Condicional*	ID del token (debe ser diferente al principal). Requerido solo si se provee `backupPaymentMethod`
`authenticationId`	string	❌	ID de autenticación 3DS (null en primera petición)
`billingInfo`	object	Condicional*	Información de facturación, puede ser null
`billingInfo.countryCode`	string	Condicional*	Código del país
`billingInfo.stateCode`	string	Condicional*	Código del estado
`billingInfo.zipCode`	string	Condicional*	Código postal
`locationCode`	string	✅	Código de la sucursal, Se obtiene desde Portal → Configuración → Sucursales → Editar → abajo del campo Teléfono

Billing Info

El objeto billingInfo es requerido únicamente cuando el país emisor de la tarjeta es USA o CAN. Puedes determinarlo a partir del código de país del BIN del método de pago.

Location Code

El locationCode lo encuentras en el portal al editar tu sucursal, justo debajo del número de teléfono. No confundir con locationId.

- Parámetros de Respuesta

Parámetro	Tipo	Descripción
`status`	string	Estado del cobro (`FAILED`, `SUCCEEDED`, `AUTHENTICATION_REQUIRED`)
`message`	string	Descripción del resultado
`error`	object	Código y mensaje de error (cuando aplica)
`authentication`	object	URL e ID de autenticación 3DS (cuando aplica)
`subscription`	object	Información de la suscripción creada
`payment`	object	Información del pago realizado

- Estados de la suscripción

1. FAILED (Pago Fallido)

El proceso de pago ha fallado. El nodo error contendrá los detalles.

Details

Ver ejemplo de respuesta

{
    "status": "FAILED",
    "message": "El pago no se pudo procesar: Necesitamos más validaciones, por favor contacta a servicio al cliente al +50324086126. Id: 1b44231a-1cfc-424d-9573-0a3a3ff756bd",
    "error": {
        "code": "FRAUD_PREVENT",
        "message": "Necesitamos más validaciones, por favor contacta a servicio al cliente al +50324086126",
        "title": "Error en la transacción",
        "detail": "Necesitamos más validaciones, por favor contacta a servicio al cliente al +50324086126"
    },
    "authentication": null,
    "subscription": null,
    "payment": null
}

2. SUCCEEDED (Pago Exitoso)

El proceso de pago se completó correctamente.

Details

Ver ejemplo de respuesta

{
    "status": "SUCCEEDED",
    "message": "El pago fue realizado exitosamente",
    "error": null,
    "authentication": null,
    "subscription": {
        "subscriptionId": 481,
        "planId": 1544,
        "name": "Plan ePay",
        "description": "Descripción de la suscripción ePay",
        "created": "2025-10-24T21:22:47.7452894Z",
        "amount": 45.9900,
        "amountFormatted": "$45.99",
        "billingCycle": 1,
        "billingCycleType": "Mes",
        "currencyCode": "USD",
        "locale": "es-SV",
        "currentPeriodStart": "2025-10-24T21:22:47.4571820Z",
        "currentPeriodEnd": "2025-10-25T21:22:47.4571820Z",
        "timezone": "America/El_Salvador",
        "subscriptionStatus": "Activa",
        "customer": {
            "name": "Carlos Dúran",
            "email": "[email protected]",
            "phone": "+50364331900",
            "paymentMethodName": "TEST 001",
            "paymentMethodCardBrand": "visa",
            "paymentMethodBin": "400000",
            "paymentMethodLastDigits": "2701",
            "backupPaymentMethodName": "TEST 002",
            "backupPaymentMethodCardBrand": "visa",
            "backupPaymentMethodBin": "424242",
            "backupPaymentMethodLastDigits": "4242"
        }
    },
    "payment": {
        "chargeId": "676a97bb-f19e-4311-aac7-b9c6911c3a1d",
        "authorizationCode": "831000"
    }
}

3. AUTHENTICATION_REQUIRED (Requiere Autenticación 3DS)

Si el estado es AUTHENTICATION_REQUIRED, la API te devolverá una URL de autenticación. Debes guiar al usuario a través de este flujo (en este caso es necesario el uso de un iframe).

Guía de Autenticación 3DS

Para una guía detallada sobre cómo implementar el iframe y manejar el flujo 3DS, consulta nuestra documentación de Autenticación 3D Secure.

Details

Ver ejemplo de respuesta

{
    "status": "AUTHENTICATION_REQUIRED",
    "message": "El pago requiere autenticación 3DS",
    "error": null,
    "authentication": {
        "url": "https://front-3ds.h4b.dev/authentication/9b77e558-7d5d-4fdd-b84c-f295225ba2e1?showBranding=True&lang=es",
        "id": "9b77e558-7d5d-4fdd-b84c-f295225ba2e1"
    },
    "subscription": null,
    "payment": {
        "chargeId": null,
        "authorizationCode": null
    }
}

📌 Consultar el detalle de una suscripción

URL base: https://api-sandbox.n1co.shop
Método: GET
Endpoint: /api/v3/Subscriptions/{subscriptionId}
Descripción: Obtiene la información de una suscripción.
Cabeceras necesarias:
Authorization: Bearer {your_token}
Ejemplo de respuesta:

Response

{
    "subscriptionId": 480,
    "planId": 1544,
    "name": "Plan ePay",
    "description": "Descripción de la suscripción ePay",
    "created": "2025-10-15T21:36:26.9682946Z",
    "amount": 45.9900,
    "amountFormatted": "$45.99",
    "billingCycle": 1,
    "billingCycleType": "Mes",
    "currencyCode": "USD",
    "locale": "es-SV",
    "currentPeriodStart": "2025-10-16T21:36:26.7660968Z",
    "currentPeriodEnd": "2025-11-16T21:36:26.7660968Z",
    "timezone": "America/El_Salvador",
    "subscriptionStatus": "Activa",
    "customer": {
        "name": "Carlos Dúran",
        "email": "[email protected]",
        "phone": "+50364331900",
        "paymentMethodName": "TEST 001",
        "paymentMethodCardBrand": "visa",
        "paymentMethodBin": "400000",
        "paymentMethodLastDigits": "2701",
        "backupPaymentMethodName": "TEST 002",
        "backupPaymentMethodCardBrand": "visa",
        "backupPaymentMethodBin": "424242",
        "backupPaymentMethodLastDigits": "4242"
    }
}

📌 Consultar las órdenes de una suscripción.

URL base: https://api-sandbox.n1co.shop
Método: GET
Endpoint: /api/v3/Subscriptions/{subscriptionId}/orders
Descripción: Obtiene el detalle de las órdenes realizadas en una suscripción.
Cabeceras necesarias:
Authorization: Bearer {your_token}
Ejemplo de respuesta:

Response

[
{
    "subscriptionId": 475,
    "planId": 576,
    "orderId": 49068,
    "orderName": "Plan ePay",
    "total": 10.9900,
    "orderStatus": "Finalized",
    "createdDate": "2025-08-27T02:00:52.8551023Z",
    "createdBy": "c8573b9a-88ea-45b6-aef4-4817440f2cc9"
},
{
    "subscriptionId": 475,
    "planId": 576,
    "orderId": 49096,
    "orderName": "Plan ePay",
    "total": 10.9900,
    "orderStatus": "Finalized",
    "createdDate": "2025-09-27T02:00:52.8551023Z",
    "createdBy": "c8573b9a-88ea-45b6-aef4-4817440f2cc9"
}
]

📌 Gestionar cancelaciones de suscripciones.

URL base: https://api-sandbox.n1co.shop
Método: POST
Endpoint: /api/v3/Subscriptions/{subscriptionId}/cancel
Descripción: Cancelar una suscripción.
Cabeceras necesarias:
Content-Type: application/json
Authorization: Bearer {your_token}
Ejemplo:

Request
Response

{
    "reason": "Cliente ya no quiere el servicio"
}

468 //subscriptionId que fue cancelada

Suscripciones

Ciclo de vida de una suscripción​

Funcionalidades​

📌 Creación de suscripciones para un cliente a un plan específico.​

- Parámetros de la petición​

- Parámetros de Respuesta​

- Estados de la suscripción​

1. FAILED (Pago Fallido)​

2. SUCCEEDED (Pago Exitoso)​

3. AUTHENTICATION_REQUIRED (Requiere Autenticación 3DS)​

📌 Consultar el detalle de una suscripción​

📌 Consultar las órdenes de una suscripción.​

📌 Gestionar cancelaciones de suscripciones.​

Ciclo de vida de una suscripción

Funcionalidades

📌 Creación de suscripciones para un cliente a un plan específico.

- Parámetros de la petición

- Parámetros de Respuesta

- Estados de la suscripción

1. FAILED (Pago Fallido)

2. SUCCEEDED (Pago Exitoso)

3. AUTHENTICATION_REQUIRED (Requiere Autenticación 3DS)

📌 Consultar el detalle de una suscripción

📌 Consultar las órdenes de una suscripción.

📌 Gestionar cancelaciones de suscripciones.