Zelle
Introducción
Este documento proporciona las especificaciones para implementar la validación de pago en Zelle a través del API de Luka.
La URL está especificada en Ambientes.
La autenticación se realiza a través de un token (JWT) que retorna el método de login con las credenciales proporcionadas por Lukapay. Ver documentación.
Validación de pago Zelle
Permite registrar y validar un pago realizado a través de Zelle. Si el pago existe en la cuenta, se aprueba de forma automática de lo contrario queda en revisión.
Solicitud
POST {URL}/api/v1/Transaccion/zelle.registrar.token
Cabeceras
Authorization: Bearer {token}
userIp: {dirección IP del cliente}
Cuerpo de la solicitud
| Nombre del campo | Descripción | Tipo | Obligatorio |
|---|---|---|---|
| codigoAutorizacion | Código de autorización del Zelle | String | Sí |
| monto | Monto de la operación | Number | Sí |
| Correo electrónico del cliente | String | Sí | |
| nombrePagador | Nombre del titular de la cuenta de Zelle | String | Sí |
| referencia | Valor opcional que permite identificar algo relacionado con el pago | String | No |
| trazaId | Identificador único de trazabilidad en la base de datos del comercio | String | Sí |
Ejemplo
{
"codigoAutorizacion": "012345678",
"monto": 1.0,
"email": "email@example.com",
"nombrePagador": "Pedro Perez",
"referencia": "V14816397",
"trazaId": "bfcd304f-452a-4eef-be9c-b180c5b36b4c"
}
Respuesta
Éxito
{
"Monto": 0,
"MontoUsd": 0,
"InfoProceso": {
"EstatusProcesamiento": "success",
"CodigoRespuestaCvv": null
},
"TarjetaHabiente": null,
"InfoUsuarioPagador": {
"Nombre": "Pedro",
"Apellido": "Perez",
"NumeroIdentidad": null,
"NumeroTelefono": null,
"Email": "info@example.com"
},
"Moneda": "USD",
"InfoTarjeta": null,
"TransaccionId": 80001,
"TransaccionMerchantId": 0,
"Descripcion": "transacción aprobada",
"TrazaId": "f615929r-5y03-4x18-x94b-oo42e90f7718",
"Exitoso": true,
"Canal": "Pasarela de pago",
"MedioDePago": "Zelle",
"MontoOriginal": null,
"MerchantId": "x36xxdd00",
"FechaOperacion": "2023-04-01 13:34:51.882562+00:00",
"CargosAdicionales": null
}
Pendiente
{
"Monto": 0,
"MontoUsd": 0,
"InfoProceso": {
"EstatusProcesamiento": "pending",
"CodigoRespuestaCvv": null
},
"TarjetaHabiente": null,
"InfoUsuarioPagador": {
"Nombre": "Pedro",
"Apellido": "Perez",
"NumeroIdentidad": null,
"NumeroTelefono": null,
"Email": "info@example.com"
},
"Moneda": "USD",
"InfoTarjeta": null,
"TransaccionId": 80002,
"TransaccionMerchantId": 0,
"Descripcion": "transacción en revisión",
"TrazaId": "9b2nnn1b-326n-436n-8hnf-0a000oklcf3h9",
"Exitoso": true,
"Canal": "Pasarela de pago",
"MedioDePago": "Zelle",
"MontoOriginal": null,
"MerchantId": "lkj55jj11",
"FechaOperacion": "2023-04-01 13:36:47.588913+00:00",
"CargosAdicionales": null
}
Webhook para Pagos Diferidos
Nuestra plataforma tiene la capacidad de validar en línea la referencia registrada por el usuario, sin embargo, es posible que no la encuentre de forma automática. En este caso, marcamos la transacción como Pendiente por revisión.
Cuando la transacción queda con estatus pendiente, se vuelve a revisar automáticamente cada 2 minutos hasta 5 intentos, pero si de todas formas no se encuentra, se hace una revisión manual.
En este caso se debe mostrar un mensaje al usuario indicando que su pago será revisado y recibirá la respuesta vía correo, ya sea aprobada o rechazada.
A efectos de la integración, en la respuesta, el campo Exitoso tendrá el valor true pero también se debe revisar la propiedad InfoProceso.EstatusProcesamiento, la cual indica el estatus real del pago.
Las 2 posibilidades son: success (exitoso) o pending (pendiente) tal como se muestra a continuación:
"InfoProceso":{
"EstatusProcesamiento":"pending",
"CodigoRespuestaCvv":null
}
Para recibir el estatus final de la transacción, se envía la respuesta a través de un webhook.
En este caso, el integrador debe crear una función en su API que reciba la respuesta de Lukapay y actualice el estatus de la transacción en su sistema.
El objeto con la respuesta que se envía a través del método POST y tiene el siguiente formato:
[
{
"Monto": 16.03,
"Id": 8357,
"IdTraza": "1234567890",
"CodigoAutorizacion": "kjfkgds874k",
"Estatus": {
"Id": 6,
"Descripcion": "Tx Exitosa"
},
"Fecha": "2022-02-23T18
:27:47.0170155Z",
"FechaCreacion": "2022-02-23T18:27:47.1959116Z"
},
{
"Monto": 1.0,
"Id": 3547,
"IdTraza": "1234567890",
"CodigoAutorizacion": "kljghdfjg45646",
"Estatus": {
"Id": 7,
"Descripcion": "Tx Fallida"
},
"Fecha": "2021-04-23T22:10:29.4103Z",
"FechaCreacion": "2021-04-23T22:10:29.4519723Z"
}
]
Cuerpo de la solicitud (Schema)
| Nombre del campo | Descripción | Tipo | Obligatorio |
|---|---|---|---|
| Monto | Monto de la operación | double | Sí |
| Id | Identificador de la transacción en Luka | integer | Sí |
| IdTraza | Identificador único de trazabilidad en la base de datos del comercio | string | Sí |
| CodigoAutorizacion | Código de autorización del Zelle | string | Sí |
| Estatus | Objeto con el detalle del estado de la transacción | objeto | Sí |
| Estatus.Id | ID del estado de la operación devuelto por Lukapay. Valores posibles: 6 (exitoso), 7 (fallido) | integer | Sí |
| Estatus.Descripcion | Nombre del estado de la operación devuelto por Lukapay. Valores posibles: Tx Exitosa, Tx Fallida | string | Sí |
| Fecha | Fecha de la operación | string | Sí |
| FechaCreacion | Fecha de la operación | string | Sí |
Nota: Una vez creado el endpoint del webhook, se debe enviar esta información al equipo de desarrollo de Luka para proceder a configurarlo en el servicio.
Códigos de error
| Código | Mensaje |
|---|---|
| 401 | acceso no autorizado |
| 400 | el pago ya fue registrado |
| 400 | referencia inválida |
| 400 | la moneda no está soportada |
| 500 | ocurrió un error inesperado |
Example Value
{
"mensaje": "string",
"codigo": 0,
"continua": true,
"mensajeId": "string"
}
Webhooks para pagos diferidos
Nuestra plataforma valida en línea la referencia de pago registrada por el usuario. Si no se encuentra automáticamente, la transacción se marca como "Pendiente por revisión" y se reintenta hasta 5 veces cada 2 minutos. Si aún no se encuentra, se revisa manualmente. En estos casos, el usuario es notificado por correo. En la integración, el campo Exitoso será true, pero se debe verificar InfoProceso.EstatusProcesamiento para conocer el estatus real del pago: success (exitoso) o pending (pendiente). El estatus final se envía a través de un webhook.