Saltar al contenido principal

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ónTransición
1Se creó una suscripción con éxito.Inicio → Activa
2Ejecución de pago recurrente exitoso.Activa/Pendiente → Activa
3El administrador bloqueó la suscripción.Activa → Bloqueada
4El administrador desbloqueó la suscripción.Bloqueada → Activa
5El comprador desactivó su suscripción.Activa → Inactiva
6Error en pago recurrente (diario/semanal) - intentos = 1.Activa → Inactiva
7El link de suscripción no es válido (caducado, inactivo o eliminado).Activa/Bloqueada/Pendiente → Inactiva
8Error en pago recurrente (mensual/anual) - intentos <= 2.Activa → Pendiente
9Error en pago recurrente (mensual/anual) - intentos = 3.Pendiente → Inactiva
10Error 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:
{
    "planId": 1544,
    "customer": {
        "id": "Customer001",
        "name": "Carlos Dúran",
        "email": "carlos.duran@gmail.com",
        "phoneNumber": "+50364331900"
    },
    "paymentMethod": {
        "id": "689f93049b36afba505e7bc8"
    },
    "backupPaymentMethod": {
        "id": "689f69319b36afba505e7bc0"
    },
    "authenticationId": null,
    "billingInfo": {
        "countryCode": "string",
        "stateCode": "string",
        "zipCode": "string"
    },
    "locationCode": "N1C0CD001"
}
Crear métodos de pago

Necesitarás de datos de tarjetas de pruebas →. Esta documentación te guiará a través de escenarios de prueba válidos 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ámetroTipoRequeridoDescripción
planIdinteger✅ID del plan de suscripción
customerobject✅Información del cliente
customer.idstring❌Identificador único del cliente
customer.namestring✅Nombre completo del cliente
customer.emailstring✅Email del cliente
customer.phoneNumberstring❌Número de teléfono con código de país
paymentMethodobject✅Método de pago principal
paymentMethod.idstring✅ID del token devuelto en la tokenización
backupPaymentMethodobject❌Método de pago de respaldo
backupPaymentMethod.idstringCondicional*ID del token (debe ser diferente al principal). Requerido solo si se provee backupPaymentMethod
authenticationIdstring❌ID de autenticación 3DS (null en primera petición)
billingInfoobjectCondicional*Información de facturación, puede ser null
billingInfo.countryCodestringCondicional*Código del país
billingInfo.stateCodestringCondicional*Código del estado
billingInfo.zipCodestringCondicional*Código postal
locationCodestring✅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ámetroTipoDescripción
statusstringEstado del cobro (FAILED, SUCCEEDED, AUTHENTICATION_REQUIRED)
messagestringDescripción del resultado
errorobjectCódigo y mensaje de error (cuando aplica)
authenticationobjectURL e ID de autenticación 3DS (cuando aplica)
subscriptionobjectInformación de la suscripción creada
paymentobjectInformació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": "carlos.duran@gmail.com",
            "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:
{
    "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": "carlos.duran@gmail.com",
        "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:
[
{
    "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:
{
    "reason": "Cliente ya no quiere el servicio"
}

Ejemplos: