Métodos de Pago

La API de Métodos de Pago te permite tokenizar los datos de una tarjeta. Este proceso reemplaza la información sensible (como el número de tarjeta completo) por un identificador único y no sensible, conocido como token (id).

Este paso es fundamental para garantizar la máxima seguridad y simplificar tu cumplimiento con el estándar PCI DSS. Al operar con tokens, los datos reales de la tarjeta nunca tocan tus servidores, lo que minimiza el riesgo y protege la información de tus clientes.

Puedes usar estos tokens para procesar cobros de manera segura, ya sea para transacciones únicas o para vincularlos a suscripciones, sin necesidad de volver a solicitar los datos de la tarjeta.

---

Funcionalidades

Autenticación y Seguridad

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

📌 Crear método de pago.

• URL base: https://api-sandbox.n1co.shop
• Método: POST
• Endpoint: /api/v3/PaymentMethods
• Descripción: Crear método de pago para tokenizar los datos de la tarjeta.
• Cabeceras necesarias:
• Content-Type: application/json
• Authorization: Bearer {your_token}
• Ejemplo:

Request

{
    "customer": {
        "id": "customer001",
        "name": "Carlos Dúran",
        "email": "[email protected]",
        "phoneNumber": "+50364331900"
    },
    "card": {
        "number": "4000000000002701",
        "cardHolder": "CARLOS DURAN",
        "expirationMonth": "10",
        "expirationYear": "2028",
        "cvv": "111",
        "singleUse": false
    }
}

Response

{
    "id": "69167196381d34f25eb22e9d",
    "type": "card",
    "bin": {
        "brand": "visa",
        "issuerName": "INTL HDQTRS-CENTER OWNED",
        "countryCode": "SLV"
    },
    "success": true,
    "message": "El método de pago se creó exitosamente"
}

- Parámetros de la petición

Parámetro	Tipo	Requerido	Descripción
customer	object	✅	Objeto que contiene la información del cliente.
customer.id	string	✅	Identificador único para tu cliente.
customer.name	string	✅	Nombre completo del cliente.
customer.email	string	✅	Correo electrónico del cliente.
customer.phoneNumber	string	✅	Número de teléfono del cliente (ej. "+50364331900").
card	object	✅	Objeto que contiene los datos de la tarjeta.
card.number	string	✅	Número de la tarjeta de crédito o débito.
card.cardHolder	string	✅	Nombre del titular de la tarjeta, tal como aparece en ella.
card.expirationMonth	string	✅	Mes de expiración de la tarjeta (ej. "09").
card.expirationYear	string	✅	Año de expiración de la tarjeta (ej. "2030").
card.cvv	string	✅	Código de seguridad de la tarjeta (CVV, CVC).
card.singleUse	boolean	✅	Define si el token generado será de un solo uso (true) o multiuso (false).

¿Como usar card.singleUse?

Este parámetro booleano determina la vida útil del token generado:

• card.singleUse: true (Recomendado para Pagos Únicos): El token generado será de un solo uso y se invalidará automáticamente después de ser utilizado en un cobro. Es la opción ideal para transacciones donde el cliente no desea guardar su tarjeta para futuras compras.

• card.singleUse: false (Requerido para Suscripciones y Tarjetas Guardadas): El token será multiuso, lo que permite utilizarlo para múltiples cobros. Debes usar esta opción si planeas:

  • Vincular el método de pago a una suscripción.
  • Guardar la tarjeta en el perfil de un cliente para facilitar compras futuras.

- Parámetros de Respuesta

Parámetro	Tipo	Descripción
id	string	El identificador único del método de pago (token).
type	string	Tipo de método de pago, en este caso, "card".
bin	object	Objeto con información del BIN de la tarjeta.
bin.brand	string	La marca de la tarjeta (ej. "visa", "mastercard").
bin.issuerName	string	Nombre del banco emisor de la tarjeta.
bin.countryCode	string	Código del país emisor de la tarjeta (ej. "SLV").
success	boolean	Indica si la creación del método de pago fue exitosa.
message	string	Mensaje descriptivo del resultado de la operación.

---

📌 Actualizar método de pago.

• URL base: https://api-sandbox.n1co.shop
• Método: PUT
• Endpoint: /api/v3/PaymentMethods
• Descripción: Actualizar método de pago.
• Cabeceras necesarias:
• Content-Type: application/json
• Authorization: Bearer {your_token}
• Ejemplo:

Request

{
    "customerId": "customer001",
    "cardId": "69167196381d34f25eb22e9d",
    "card": {
        "cardHolder": "CARLOS DURAN",
        "expirationMonth": "12",
        "expirationYear": "2030",
        "cvv": "111"
    }
}

Response

{
    "id": "69167196381d34f25eb22e9d",
    "type": "card",
    "bin": {
        "brand": "visa",
        "issuerName": "INTL HDQTRS-CENTER OWNED",
        "countryCode": "SLV"
    },
    "success": true,
    "message": "El método de pago actualizado"
}