Ejemplos
Ejemplo de flujo de pago
Este ejemplo muestra cómo realizar un flujo de pago completo utilizando el API ePay.
Paso 1: Autenticación
Primero, debes autenticarte en el API ePay para obtener un token de acceso. Para ello, realiza una
solicitud POST al endpoint de autenticación con tu clientId y clientSecret.
curl --location '{{API_BASE_URL}}/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"clientId": "{{CLIENT_ID}}",
"clientSecret": "{{CLIENT_SECRET}}",
}'
La respuesta será un token de acceso que debes incluir en las cabeceras de tus solicitudes al API.
{
"accessToken": "some-access-token", // Token de acceso
"tokenType": "Bearer", // Tipo de token
"expiresIn": 3600 // Tiempo de expiración en segundos
}
Paso 2: Crear método de pago
A continuación, crea un método de pago utilizando el endpoint de creación de métodos de pago.
curl --location '{{API_BASE_URL}}/paymentmethods' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--data-raw '{
"customer": {
"id": "some-customer-id",
"name": "Tim Cook",
"email": "tim.cook@apple.com",
"phoneNumber": "+1 408-555-5555"
},
"card": {
"number": "4000000000001000",
"expirationMonth": "12",
"expirationYear": "2030",
"cvv": "123",
"cardHolder": "TIM COOK",
"singleUse": false
}
}'
La respuesta será un objeto que contiene el ID del método de pago creado.
{
"id": "663d52c0e044fede8ea1edbf", // ID del método de pago
"type": "card",
"bin": {
"brand": "Visa",
"issuerName": "ITS BANK",
"countryCode": "USA"
}, // Información del BIN
"success": true, // Indica si la operación fue exitosa
"message": "El método de pago se creó exitosamente"
}
Paso 3: Realizar una transacción
Finalmente, realiza una transacción utilizando el endpoint de cobros.
curl --location '{{API_BASE_URL}}/charges' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--data-raw '{
"order": {
"id": "your-order-id",
"amount": 10,
"description": "some-description",
"name": "some-name"
},
"cardId": "663d52c0e044fede8ea1edbf",
"authenticationId": null,
"billingInfo": {
"countryCode": "USA",
"stateCode": "NC",
"zipCode": "27244"
}
}'
La información de facturación (billingInfo) es requerida únicamente cuando el país emisor de la tarjeta es USA o CAN.
Esto lo puedes determinar a partir del código de país del BIN del método de pago.
A continuación, se describen los parámetros de respuesta al realizar un cobro:
| Parámetro | Tipo | Descripción |
|---|---|---|
| status | String | Indica el estado del cobro. |
| message | String | Describe el resultado del parámetro status. |
| error | Object | Objeto que contiene el código y mensaje de error. |
| authentication | Object | Objeto que contiene la URL de autenticación y el id de validación para completar la transacción. |
| order | Object | Objeto que contiene la información de la orden de compra. |
| createdAt | DateTime | Fecha y hora de la transacción en UTC. |
Estados de cobro (status)
Existen 3 posibles estados de cobro:
FAILED
Este estado representa que el proceso de pago ha fallado. El nodo error contendrá el código y mensaje de error.
Ejemplo:
{
"status": "FAILED",
"message": "El pago no se pudo procesar: Cobro en Validación, Contactar a nuestro departamento de Servicio al Cliente al +50324086126. Id: 1a77edab-f826-4693-addb-bf0743702270",
"error": {
"code": "FRAUD_PREVENT",
"message": "Cobro en Validación, Contactar a nuestro departamento de Servicio al Cliente al +50324086126"
},
"authentication": null,
"order": null,
"createdAt": "2023-08-23T22:57:50.1154760Z"
}
SUCCEEDED
Este estado representa que el proceso de pago se ha realizado exitósamente.
Ejemplo:
{
"status": "SUCCEEDED",
"message": "El pago fue realizado exitosamente",
"error": null,
"authentication": null,
"order": {
"id": "1", // n1co order id
"reference": "your-order-id", // your order id
"amount": 10,
"currency": "USD",
"authorizationCode": "176981"
},
"createdAt": "2023-08-24T02:03:55.5851570Z"
}
AUTHENTICATION_REQUIRED
Este estado representa que la transacción requiere autenticación 3DS.
Ejemplo:
{
"status": "AUTHENTICATION_REQUIRED",
"message": "El pago requiere autenticación 3DS",
"error": null,
"authentication": {
"url": "https://front-3ds.h4b.dev/authentication/b574cee2-1ce7-4aa7-b176-8a6390e91081",
"id": "b574cee2-1ce7-4aa7-b176-8a6390e91081"
},
"order": null,
"createdAt": "2023-09-28T18:53:51.1070240Z"
}
Para validar la transacción, se debe redirigir al comprador a la URL proporcionada en el nodo authentication usando un iframe. A continuación se proporcionan ejemplos de implementación de iframe:
Expliación de la implementación
Para el manejo de este caso, el proyecto de frontend debe agregar un event listener que escuche el postMessage que se envía desde el iframe. La estructura del mensaje es la siguiente:
{
"MessageType": string,
"Status": string,
"AuthenticationId": string,
"OrderId": string,
"OrderAmount": number
}
MessageType
-
authentication.complete→ autenticación completada exitósamente -
authentication.failed→ error al procesar la autenticación
Status
-
PENDING→ pendiente de autenticación -
SUCCESS→ autenticación exitosa -
FAILED→ no se logro autenticar con el banco emisor -
ERROR→ error interno del procesador de pagos -
EXPIRED→ la autenticación ha expirado
Una vez que se reciba el mensaje con MessageType = "authentication.complete" y Status = "SUCCESS", se debe realizar una nueva solicitud de cobro. En esta ocasión, se debe incluir el authenticationId recibido en el mensaje anterior para completar la transacción.
curl --location '{{API_BASE_URL}}/charges' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--data-raw '{
"order": {
"id": "your-order-id",
"amount": 10,
"description": "some-description",
"name": "some-name"
},
"cardId": "663d52c0e044fede8ea1edbf",
"authenticationId": "b574cee2-1ce7-4aa7-b176-8a6390e91081",
"billingInfo": {
"countryCode": "USA",
"stateCode": "NC",
"zipCode": "27244"
}
}'
La respuesta será similar a la anterior, con el estado de la transacción y la información de la orden de compra.