Aceptar Pagos

Con esta API, podrás integrar un sistema de cobros en tu plataforma, facilitando pagos únicos y devoluciones.

Funcionalidades

Autenticación y Seguridad

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

📌 Generar cobro a un cliente.

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

Request
Response

{
    "customer": {
        "id": "customer114",
        "name": "Carlos Pérez",
        "email": "[email protected]",
        "phoneNumber": "+50370000000"
    },
    "order": {
        "id": "EPAY001",
        "amount": 200.9,
        "description": "Estufa eléctrica G.E modelo JJCBS631SFSS",
        "name": "Compra de cocina"
    },
    "cardId": "69167196381d34f25eb22e9d",
    "authenticationId": null,
    "billingInfo": {
        "countryCode": "US",
        "stateCode": "CA",
        "zipCode": "10002"
    },
    "locationCode": "N1C0CD001"
}

{
    "status": "SUCCEEDED",
    "message": "El pago fue realizado exitosamente",
    "error": null,
    "authentication": null,
    "order": {
        "id": "50582",
        "reference": "EPAY001",
        "amount": 200.9,
        "captureAmount": 200.9,
        "currency": "USD",
        "authorizationCode": "217982"
    },
    "createdAt": "2025-12-04T17:35:48.6318771Z"
}

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 cardId (Requerido).

- Parámetros de la petición

Parámetro	Tipo	Requerido	Descripción
`customer`	object	❌	Información del cliente (recomendado)
`customer.id`	string	❌	Identificador único del cliente
`customer.name`	string	❌	Nombre completo del cliente (máx. 255)
`customer.email`	string	❌	Email del cliente; si se envía debe ser válido (máx. 255)
`customer.phoneNumber`	string	❌	Número de teléfono con código de país
`order`	object	✅	Información de la orden
`order.id`	string	✅	Identificador único de la orden
`order.amount`	decimal	Condicional	Monto a cobrar, mayor a 0. Requerido si no envías `order.lineItems`; debe omitirse si los envías
`order.lineItems`	array	Condicional	Productos de la orden. Requerido si no envías `order.amount`; debe omitirse si lo envías. No se permiten SKU repetidos
`order.lineItems[].sku`	string	Condicional	SKU de un producto de tu catálogo; debe existir en tu tienda. Requerido si no envías `product`
`order.lineItems[].quantity`	integer	✅	Cantidad, mayor a 0
`order.lineItems[].product`	object	Condicional	Producto descrito en la petición, para cobrar algo que no está en tu catálogo
`order.lineItems[].product.name`	string	Condicional	Nombre del producto. Requerido si envías `product`
`order.lineItems[].product.price`	decimal	Condicional	Precio unitario, mayor a 0. Requerido si envías `product`
`order.lineItems[].product.description`	string	❌	Descripción del producto
`order.lineItems[].product.imageUrl`	string	❌	URL de la imagen del producto (máx. 512)
`order.description`	string	❌	Descripción de la orden
`order.name`	string	✅	Nombre de la orden (máx. 150)
`cardId`	string	✅	ID del token devuelto en la tokenización
`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. Si se omite, se usa la sucursal activa marcada como predeterminada. 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)
`order`	object	Objeto que contiene la información de la orden de compra
`createdAt`	object	Fecha de creación del pago

- Estados

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,
    "order": null,
    "createdAt": "2025-12-04T17:51:59.1548011Z"
}

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,
    "order": {
        "id": "50582",
        "reference": "EPAY001",
        "amount": 200.9,
        "captureAmount": 200.9,
        "currency": "USD",
        "authorizationCode": "217982"
    },
    "createdAt": "2025-12-04T17:51:59.1548011Z"
}

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-sandbox.n1co.com/authentication/9b77e558-7d5d-4fdd-b84c-f295225ba2e1?showBranding=True&lang=es",
        "id": "9b77e558-7d5d-4fdd-b84c-f295225ba2e1"
    },
    "order": null,
    "createdAt": "2025-12-04T17:51:59.1548011Z"
}

📌 Generar devolución de un cobro

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

Request
Response

{
    "orderId": "50634",
    "cancellationReason": "Producto en mal estado fue devuelto por el cliente"
}

{
    "success": true,
    "message": "Su orden ha sido cancelada y su pago reintegrado",
    "orderId": "50634",
    "status": "SUCCEEDED",
    "amount": 200.9000,
    "currency": "USD"
}

Aceptar Pagos

Funcionalidades​

📌 Generar cobro a un cliente.​

- Parámetros de la petición​

- Parámetros de Respuesta​

- Estados​

1. FAILED (Pago Fallido)​

2. SUCCEEDED (Pago Exitoso)​

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

📌 Generar devolución de un cobro​

Funcionalidades

📌 Generar cobro a un cliente.

- Parámetros de la petición

- Parámetros de Respuesta

- Estados

1. FAILED (Pago Fallido)

2. SUCCEEDED (Pago Exitoso)

3. AUTHENTICATION_REQUIRED (Requiere Autenticación 3DS)

📌 Generar devolución de un cobro