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

{
    "customer": {
        "id": "customer114",
        "name": "Carlos Dúran",
        "email": "[email protected]",
        "phoneNumber": "+50364331900"
    },
    "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"
}

Response

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

- Parámetros de la petición

Parámetro	Tipo	Requerido	Descripció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
order	object	✅	Información de la orden
order.id	string	✅	Identificador único de la orden
order.amount	decimal	✅	Monto a cobrar
order.description	string	❌	Descripción de la orden
order.name	string	✅	Nombre de la orden
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, 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.h4b.dev/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

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

Response

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