BNC
Introducción
Este documento proporciona las especificaciones para implementar los métodos de pagos de BNC 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.
Métodos de Pago
Pago Móvil
Registra y valida pagos realizados a través de la Pago Móvil.
📄 Tarjeta de Débito
Realiza pagos con tu tarjeta de débito.
📄 Tarjeta de Crédito
Realiza pagos con tu tarjeta de crédito.
Pago Móvil
Permite registrar y validar pagos realizados a través de la modalidad de pago móvil.
Request
POST {URL}/api/v1/transaccion/bnc.registar.pago.movil
Headers
Content-Type: application/json
Authorization: Bearer {token}
userIp: {dirección IP del cliente}
Body
| Nombre del campo | Descripción | Tipo | Obligatorio |
|---|---|---|---|
| NombrePagador | Nombre del cliente | String | No |
| CodigoBancoPagador | Código del banco destino de los fondos | String | Sí |
| TelefonoPagador | Número de teléfono desde donde se realizó el pago móvil | String | Sí |
| Cedula | Documento de identificación del cliente natural o jurídico beneficiario de los fondos | String | Sí |
| NumeroReferencia | Número de referencia del pago móvil realizado | String | Sí |
| TelefonoReceptor | Número de teléfono donde se recibe el pago móvil | String | No |
| Monto | Monto de la operación | Number | Sí |
| Dirección de correo electrónico del cliente que realiza el pago | String | Sí | |
| TrazaId | Identificador único de trazabilidad en la base de datos del comercio | String | Sí |
| Referencia | Identificación del cliente final en caso de que se requiera | String | No |
| IdCanal | Canal por donde realiza la operación. Posibles valores: 1: Pasarela, 2: API (default), 3: Link de Pago, 4: Android, 5: iOS | Number | No |
| FechaMovimiento | Fecha en la que se realizó el pago móvil. Formato: “YYYYMMDD” | String | No |
Response
| Nombre | Descripción | Tipo |
|---|---|---|
| Canal | Indica el canal que se está utilizando para aplicar el pago en Lukapay | Number |
| CargosAdicionales | Objeto que contiene cargos adicionales. | Object |
| Cuotas | Objeto que contiene información sobre cuotas. | Object |
| Descripción | Contiene la respuesta de la aplicación del pago, como estatus de la transacción y cualquier información adicional | String |
| Exitoso | Indica si la transacción fue exitosa o no. Se utiliza para validar la respuesta | Boolean |
| FechaOperacion | Fecha que ocurrió la transacción | String |
| InfoProceso | Objeto que contiene información más detallada del estatus de la transacción | Object |
| InfoTarjeta | Objeto que contiene información de la tarjeta de crédito utilizada para realizar el pago. Solo aplica para pagos con tarjeta | Object |
| InfoUsuarioPagador | Objeto que devuelve información básica del usuario que realiza el pago | Object |
| MedioDePago | Indica el método de pago que se utilizó | String |
| MerchantId | Referencia de la transacción del merchant utilizado para aplicar el pago | String |
| Moneda | Código de la moneda utilizada para realizar el pago | String |
| Monto | Indica el monto del pago realizado | Number |
| MontoOriginal | Objeto con información del monto original. Se utiliza cuando se debe aplicar una conversión de moneda | Object |
| MontoUsd | Valor del monto en dólar estadounidense. Se utiliza cuando se especifica el MontoOriginal | Number |
| TarjetaHabiente | Objeto que contiene información del pagador (en caso de haber sido especificado) | Object |
| TransaccionId | Referencia de la transacción en Lukapay | Number |
| TransaccionMerchantId | Referencia de la transacción del merchant utilizado para aplicar el pago | Number |
| TrazaId | Identificador interno del comercio. En caso de que el comercio no lo proporcione se genera un código aleatorio. | String |
Los atributos de los objetos están especificados en Respuesta de transacción.
Ejemplo de uso
Request Body
{
"Cedula": "V12345678",
"NombrePagador": "Pedro Perez",
"CodigoBancoPagador": "0191",
"TelefonoPagador": "584121234567",
"FechaTransaccion": "20240807",
"NumeroReferencia": "12345",
"Monto": 16.03,
"Email": "demo@example.com",
"Link": null,
"MontoOriginal": null,
"Referencia": null,
"TrazaId": "1362c6e9f67e",
"IdCanal": 2,
"CargosAdicionales": null
}
Response Body
{
"Monto":16.03,
"MontoUsd":0,
"InfoProceso":{
"EstatusProcesamiento": "pending",
"CodigoRespuestaCvv": null
},
"TarjetaHabiente": null,
"Moneda":"VES",
"InfoTarjeta": null,
"InfoUsuarioPagador":{
"Nombre":"Pedro",
"Apellido":"Perez",
"Email":"demo@example.com"
},
"TransaccionId":12345,
"MerchantId":516458,
"Descripcion":"transacción en revisión",
"TrazaId":"1362c6e9f67e",
"Exitoso":true,
"MedioDePago":"Pago móvil",
"Canal":"API",
"MontoOriginal": null,
"MerchantId": "30867220134",
"FechaOperacion": "05/07/2024 19:23:20",
"CargosAdicionales": null,
"Cuotas": null
}
Auth para pago con tarjeta de débito
Permite obtener la clave de autenticación para pagar con tarjeta de débito a través de BNC.
Request
POST {URL}/api/v1/transaccion/bnc.auth
Headers
Content-Type: application/json
Authorization: Bearer {token}
Body
| Nombre del campo | Descripción | Tipo | Obligatorio |
|---|---|---|---|
| Cedula | Documento de identificación asociada a la tarjeta de débito a pagar | String | Sí |
| Tarjeta | Número de la tarjeta de débito | String | Sí |
Response
| Nombre | Descripción | Tipo |
|---|---|---|
| Exitoso | Indica si la autenticación fue exitosa | Boolean |
| WorkingKey | Llave proporcionada por el banco | String |
| TipoDeAutorizacion | Tipo de autorización | String |
Ejemplo de uso
Request body
{
"cedula": "V1234",
"tarjeta": "6276123456789010"
}
Response body
{
"Exitoso": true,
"WorkingKey": "933a60e56163d38978d07c6d57e9d049",
"TipoDeAutorizacion": "otp"
}
Tarjeta de Débito
Permite realizar pagos con tarjeta de débito.
note
Necesita la autenticación como paso previo, este corresponde al método anterior.
Request
POST {URL}/api/v1/transaccion/bnc.vposDebito
Headers
Content-Type: application/json
Authorization: Bearer {token}
userIp: {dirección IP del cliente}
Body
| Nombre del campo | Descripción | Tipo | Obligatorio |
|---|---|---|---|
| Cedula | Documento de identificación asociada a la tarjeta de débito a pagar | String | Sí |
| Tarjeta | Número de la tarjeta de débito | String | Sí |
| Masterkeybnc | Corresponde al campo WorkingKey devuelto en el auth | String | Sí |
| IdTraza | Identificador único de trazabilidad en la base de datos del comercio | String | Sí |
| NombreTarjetaHabiente | Nombre del pagador | String | Sí |
| FechaExpiracion | Fecha de expiración de la tarjeta de débito. Formato: “MM/YYYY” | String | Sí |
| CodigoSeguridad | Código de seguridad CVV | String | No |
| Monto | Monto de la operación | Number | Sí |
| IdCanal | Canal por donde realiza la operación. Posibles valores: 1: Pasarela, 2: API (default), 3: Link de Pago, 4: Android, 5: iOS | Number | No |
| Dirección de correo electrónico del cliente que realiza el pago | String | Sí | |
| Clave | PIN de la tarjeta de débito | String | No |
| TipodeCuenta | Tipo de cuenta | String | Sí |
| TipoTarjeta | Tipo de tarjeta | String | No |
| CargosAdicionales | Objeto con la información de cargos adicionales | Object | No |
Response
| Nombre | Descripción | Tipo |
|---|---|---|
| Canal | Indica el canal que se está utilizando para aplicar el pago en Lukapay | Number |
| CargosAdicionales | Objeto que contiene cargos adicionales. | Object |
| Cuotas | Objeto que contiene información sobre cuotas. | Object |
| Descripción | Contiene la respuesta de la aplicación del pago, como estatus de la transacción y cualquier información adicional | String |
| Exitoso | Indica si la transacción fue exitosa o no. Se utiliza para validar la respuesta | Boolean |
| FechaOperacion | Fecha que ocurrió la transacción | String |
| InfoProceso | Objeto que contiene información más detallada del estatus de la transacción | Object |
| InfoTarjeta | Objeto que contiene información de la tarjeta de crédito utilizada para realizar el pago. Solo aplica para pagos con tarjeta | Object |
| InfoUsuarioPagador | Objeto que devuelve información básica del usuario que realiza el pago | Object |
| MedioDePago | Indica el método de pago que se utilizó | String |
| MerchantId | Referencia de la transacción del merchant utilizado para aplicar el pago | String |
| Moneda | Código de la moneda utilizada para realizar el pago | String |
| Monto | Indica el monto del pago realizado | Number |
| MontoOriginal | Objeto con información del monto original. Se utiliza cuando se debe aplicar una conversión de moneda | Object |
| MontoUsd | Valor del monto en dólar estadounidense. Se utiliza cuando se especifica el MontoOriginal | Number |
| TarjetaHabiente | Objeto que contiene información del pagador (en caso de haber sido especificado) | Object |
| TransaccionId | Referencia de la transacción en Lukapay | Number |
| TransaccionMerchantId | Referencia de la transacción del merchant utilizado para aplicar el pago | Number |
| TrazaId | Identificador interno del comercio. En caso de que el comercio no lo proporcione se genera un código aleatorio. | String |
Los atributos de los objetos están especificados en Respuesta de transacción.
Ejemplo de uso
Request body
{
"Cedula": "V12345678",
"Tarjeta": "6276123456789010",
"Masterkeybnc": "933a60e56163d38978d07c6d57e9d049",
"IdTraza": "91fcd4eda882",
"NombreTarjetaHabiente": "Pedro Perez",
"FechaExpiracion": "12/2024",
"CodigoSeguridad": "467",
"Monto": 16.03,
"IdCanal": 2,
"MontoOriginal": null,
"Link": null,
"Email": "demo@example.com",
"Clave": "1234",
"TipodeCuenta": "20",
"TipoTarjeta": "3",
"CargosAdicionales": null,
"Moneda": "VES"
}
Response body
{
"Monto": 16.03,
"MontoUsd": 0.0,
"InfoProceso": {
"EstatusProcesamiento": "success",
"CodigoRespuestaCvv": null
},
"TarjetaHabiente": {
"Nombre": "Pedro",
"Apellido": "Perez",
"NumeroIdentificacionPersonal": "V12345678",
"NumeroTelefono": null,
"LukapayId": null
},
"InfoUsuarioPagador": {
"Nombre": "Pedro",
"Apellido": "Perez",
"NumeroIdentidad": "V12345678",
"NumeroTelefono": null,
"Email": "demo@example.com"
},
"Moneda": "VES",
"InfoTarjeta": {
"Id": 0,
"UltimosCuatroDigitos": "9010",
"SubTipoTarjeta": null,
"TipoTarjeta": null,
"CategoriaTarjeta": null,
"Bin": "627612",
"FechaVencimiento": "12/2024",
"Pais": null,
"EstaBoveda": false,
"Direccion": null,
"Descripcion": null,
"IdStatus": 0,
"Moneda": null,
"Ciudad": null,
"Estado": null,
"CodigoPostal": null
},
"TransaccionId": 102295,
"TransaccionMerchantId": 121545,
"Descripcion": "transacción exitosa",
"TrazaId": "91fcd4eda882",
"Exitoso": true,
"Canal": "API",
"MedioDePago": "Débito",
"MontoOriginal": null,
"MerchantId": null,
"FechaOperacion": null,
"CargosAdicionales": null,
"Cuotas": null
}
Tarjeta de Crédito
Permite realizar pagos con tarjeta de crédito. Necesita como paso previo la autenticación que corresponde al método anterior.
Request
POST {URL}/api/v1/transaccion/bnc.vposCredito
Headers
Content-Type: application/json
Authorization: Bearer {token}
userIp: {dirección IP del cliente}
Body
| Nombre del campo | Descripción | Tipo | Obligatorio |
|---|---|---|---|
| Cedula | Documento de identificación asociada a la tarjeta de débito a pagar | String | Sí |
| Tarjeta | Número de la tarjeta de débito | String | Sí |
| IdTraza | Identificador único de trazabilidad en la base de datos del comercio | String | Sí |
| NombreTarjetaHabiente | Nombre del pagador | String | Sí |
| FechaExpiracion | Fecha de expiración de la tarjeta de débito. Formato: “MM/YYYY” | String | Sí |
| CodigoSeguridad | Código de seguridad CVV | String | No |
| Monto | Monto de la operación | Number | Sí |
| IdCanal | Canal por donde realiza la operación. Posibles valores: 1: Pasarela, 2: API (default), 3: Link de Pago, 4: Android, 5: iOS | Number | No |
| Dirección de correo electrónico del cliente que realiza el pago | String | Sí | |
| CargosAdicionales | Objeto con la información de cargos adicionales | Object | No |
Response
| Nombre | Descripción | Tipo |
|---|---|---|
| Canal | Indica el canal que se está utilizando para aplicar el pago en Lukapay | Number |
| CargosAdicionales | Objeto que contiene cargos adicionales. | Object |
| Cuotas | Objeto que contiene información sobre cuotas. | Object |
| Descripción | Contiene la respuesta de la aplicación del pago, como estatus de la transacción y cualquier información adicional | String |
| Exitoso | Indica si la transacción fue exitosa o no. Se utiliza para validar la respuesta | Boolean |
| FechaOperacion | Fecha que ocurrió la transacción | String |
| InfoProceso | Objeto que contiene información más detallada del estatus de la transacción | Object |
| InfoTarjeta | Objeto que contiene información de la tarjeta de crédito utilizada para realizar el pago. Solo aplica para pagos con tarjeta | Object |
| InfoUsuarioPagador | Objeto que devuelve información básica del usuario que realiza el pago | Object |
| MedioDePago | Indica el método de pago que se utilizó | String |
| MerchantId | Referencia de la transacción del merchant utilizado para aplicar el pago | String |
| Moneda | Código de la moneda utilizada para realizar el pago | String |
| Monto | Indica el monto del pago realizado | Number |
| MontoOriginal | Objeto con información del monto original. Se utiliza cuando se debe aplicar una conversión de moneda | Object |
| MontoUsd | Valor del monto en dólar estadounidense. Se utiliza cuando se especifica el MontoOriginal | Number |
| TarjetaHabiente | Objeto que contiene información del pagador (en caso de haber sido especificado) | Object |
| TransaccionId | Referencia de la transacción en Lukapay | Number |
| TransaccionMerchantId | Referencia de la transacción del merchant utilizado para aplicar el pago | Number |
| TrazaId | Identificador interno del comercio. En caso de que el comercio no lo proporcione se genera un código aleatorio. | String |
Los atributos de los objetos están especificados en Respuesta de transacción.
Ejemplo de uso
Request body
{
"IdTraza": "dc12c15d2cbe",
"Tarjeta": "4850123456789010",
"Cedula": "V12345678",
"NombreTarjetaHabiente": "Pedro Perez",
"FechaExpiracion": "12/2024",
"CodigoSeguridad": "123",
"Monto": 10.0,
"DireccionIp": "10.0.0.0",
"IdCanal": 2,
"MontoOriginal": null,
"Link": null,
"Email": "djcasti@gmail.com",
"BrowserAgent": "Chrome",
"Referencia": null,
"CargosAdicionales": {
"Comision": 0.0,
"OtrosCargos": [
{
"Concepto": "IVA",
"Monto": 1.6
}
],
"TotalCargos": 1.6,
"MonedaCargos": "VES"
}
Response body
{
"Monto": 10.0,
"MontoUsd": 0.0,
"InfoProceso": null,
"TarjetaHabiente": {
"Nombre": "Pedro Perez",
"Apellido": "",
"NumeroIdentificacionPersonal": null,
"NumeroTelefono": null,
"LukapayId": null
},
"InfoUsuarioPagador": null,
"Moneda": "VES",
"InfoTarjeta": {
"Id": 0,
"UltimosCuatroDigitos": "9010",
"SubTipoTarjeta": null,
"TipoTarjeta": null,
"CategoriaTarjeta": null,
"Bin": "485012",
"FechaVencimiento": "12/2024",
"Pais": null,
"EstaBoveda": false,
"Direccion": null,
"Descripcion": null,
"IdStatus": 0,
"Moneda": null,
"Ciudad": null,
"Estado": null,
"CodigoPostal": null
},
"TransaccionId": 82025,
"TransaccionMerchantId": 442528,
"Descripcion": "transacción exitosa",
"TrazaId": "dc12c15d2cbe",
"Exitoso": true,
"Canal": "API",
"MedioDePago": "Crédito",
"MontoOriginal": null,
"MerchantId": null,
"FechaOperacion": null,
"CargosAdicionales": {
"Comision": 0.0,
"OtrosCargos": [
{
"Concepto": "IVA",
"Monto": 1.6
}
],
"TotalCargos": 1.6,
"MonedaCargos": "VES"
}
}
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.