BNC
Introduction
This document provides the specifications for implementing BNC payment methods through the Luka API.
The URL is specified in Environments.
Authentication is done via a token (JWT) returned by the login method using the credentials provided by Lukapay. See documentation.
Payment methods
Mobile Payment
Register and validate payments made via Mobile Payment.
Debit Card
Make payments with your debit card.
Credit Card
Make payments with your credit card.
Mobile Payment
Allows you to register and validate payments made through mobile payment methods.
Request
POST {URL}/api/v1/transaccion/bnc.registar.pago.movil
Headers
Content-Type: application/json
Authorization: Bearer {token}
userIp: {client IP address}
Request Body
| Field Name | Description | Type | Required |
|---|---|---|---|
| NombrePagador | Name of the client | String | No |
| CodigoBancoPagador | Code of the destination bank for the funds | String | Yes |
| TelefonoPagador | Phone number from which the mobile payment was made | String | Yes |
| Cedula | Identification document of the natural or legal person receiving the funds | String | Yes |
| NumeroReferencia | Reference number of the mobile payment made | String | Yes |
| TelefonoReceptor | Phone number where the mobile payment is received | String | No |
| Monto | Amount of the operation | Number | Yes |
| Email address of the client making the payment | String | Yes | |
| TrazaId | Unique trace identifier in the merchant's database | String | Yes |
| Referencia | Identification of the final client if required | String | No |
| IdCanal | Channel through which the operation is made. Possible values: 1: Gateway, 2: API (default), 3: Payment Link, 4: Android, 5: iOS | Number | No |
| FechaMovimiento | Date when the mobile payment was made. Format: “YYYYMMDD” | String | No |
Response
| Field Name | Description | Type |
|---|---|---|
| Canal | Channel used to process the payment | Number |
| CargosAdicionales | Additional charges details | Object |
| Cuotas | Information about payment installments | Object |
| Descripción | Response providing the transaction status and any additional information | String |
| Exitoso | Indicates if the transaction was successful | Boolean |
| FechaOperacion | Date and time of the transaction | String |
| InfoProceso | Detailed information about the transaction status | Object |
| InfoTarjeta | Credit card details used for payment (if applicable) | Object |
| InfoUsuarioPagador | Information about the customer making the payment | Object |
| MedioDePago | Payment method used | String |
| MerchantId | Merchant's transaction identifier | String |
| Moneda | Currency used for the payment | String |
| Monto | Amount paid | Number |
| MontoOriginal | Information about the original amount (if currency conversion applies) | Object |
| MontoUsd | Value of the amount in U.S. dollars | Number |
| TarjetaHabiente | Payer's details if a card is used | Object |
| TransaccionId | Transaction identifier in Lukapay | Number |
| TransaccionMerchantId | Transaction identifier from the merchant | Number |
| TrazaId | Unique identifier for the transaction in the merchant's database | String |
For more details on the response objects, see Transaction Response.
Example Usage
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": "transaction under review",
"TrazaId": "1362c6e9f67e",
"Exitoso": true,
"MedioDePago": "Mobile payment",
"Canal": "API",
"MontoOriginal": null,
"MerchantId": "30867220134",
"FechaOperacion": "05/07/2024 19:23:20",
"CargosAdicionales": null,
"Cuotas": null
}
Auth for Debit Card Payment
Allows you to obtain the authentication key for paying with a debit card through BNC.
Request
POST {URL}/api/v1/transaccion/bnc.auth
Headers
Content-Type: application/json
Authorization: Bearer {token}
Request Body
| Field Name | Description | Type | Required |
|---|---|---|---|
| Cedula | Identification document associated with the debit card to be paid | String | Yes |
| Tarjeta | Debit card number | String | Yes |
Response
| Field Name | Description | Type |
|---|---|---|
| Exitoso | Indicates if the authentication was successful | Boolean |
| WorkingKey | Key provided by the bank | String |
| TipoDeAutorizacion | Type of authorization | String |
Example Usage
Request Body
{
"cedula": "V1234",
"tarjeta": "6276123456789010"
}
Response Body
{
"Exitoso": true,
"WorkingKey": "933a60e56163d38978d07c6d57e9d049",
"TipoDeAutorizacion": "otp"
}
Debit Card
Allows you to make payments with a debit card.
note
Authentication is required as a prior step; this corresponds to the previous method.
Request
POST {URL}/api/v1/transaccion/bnc.vposDebito
Headers
Content-Type: application/json
Authorization: Bearer {token}
userIp: {client IP address}
Request Body
| Field Name | Description | Type | Required |
|---|---|---|---|
| Cedula | Identification document associated with the debit card to be paid | String | Yes |
| Tarjeta | Debit card number | String | Yes |
| Masterkeybnc | Corresponds to the WorkingKey field returned in the auth | String | Yes |
| IdTraza | Unique trace identifier in the merchant's database | String | Yes |
| NombreTarjetaHabiente | Name of the cardholder | String | Yes |
| FechaExpiracion | Expiration date of the debit card. Format: “MM/YYYY” | String | Yes |
| CodigoSeguridad | Security code CVV | String | No |
| Monto | Amount of the operation | Number | Yes |
| IdCanal | Channel through which the operation is made. Possible values: 1: Gateway, 2: API (default), 3: Payment Link, 4: Android, 5: iOS | Number | No |
| Email address of the client making the payment | String | Yes | |
| Clave | Debit card PIN | String | No |
| TipodeCuenta | Type of account | String | Yes |
| TipoTarjeta | Type of card | String | No |
| CargosAdicionales | Object with information on additional charges | Object | No |
Response
| Field Name | Description | Type |
|---|---|---|
| Canal | Channel used to process the payment | Number |
| CargosAdicionales | Additional charges details | Object |
| Cuotas | Information about payment installments | Object |
| Descripción | Response providing the transaction status and any additional information | String |
| Exitoso | Indicates if the transaction was successful | Boolean |
| FechaOperacion | Date and time of the transaction | String |
| InfoProceso | Detailed information about the transaction status | Object |
| InfoTarjeta | Credit card details used for payment (if applicable) | Object |
| InfoUsuarioPagador | Information about the customer making the payment | Object |
| MedioDePago | Payment method used | String |
| MerchantId | Merchant's transaction identifier | String |
| Moneda | Currency used for the payment | String |
| Monto | Amount paid | Number |
| MontoOriginal | Information about the original amount (if currency conversion applies) | Object |
| MontoUsd | Value of the amount in U.S. dollars | Number |
| TarjetaHabiente | Payer's details if a card is used | Object |
| TransaccionId | Transaction identifier in Lukapay | Number |
| TransaccionMerchantId | Transaction identifier from the merchant | Number |
| TrazaId | Unique identifier for the transaction in the merchant's database | String |
For more details on the response objects, see Transaction Response.
Example Usage
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": "successful transaction",
"TrazaId": "91fcd4eda882",
"Exitoso": true,
"Canal": "API",
"MedioDePago": "Debit",
"MontoOriginal": null,
"MerchantId": null,
"FechaOperacion": null,
"CargosAdicionales": null,
"Cuotas": null
}
Credit Card
Allows you to make payments with a credit card. Authentication corresponding to the previous method is required.
Request
POST {URL}/api/v1/transaccion/bnc.vposCredito
Headers
Content-Type: application/json
Authorization: Bearer {token}
userIp: {client IP address}
Request Body
| Field Name | Description | Type | Required |
|---|---|---|---|
| Cedula | Identification document associated with the debit card to be paid | String | Yes |
| Tarjeta | Credit card number | String | Yes |
| IdTraza | Unique trace identifier in the merchant's database | String | Yes |
| NombreTarjetaHabiente | Name of the cardholder | String | Yes |
| FechaExpiracion | Expiration date of the credit card. Format: “MM/YYYY” | String | Yes |
| CodigoSeguridad | Security code CVV | String | No |
| Monto | Amount of the operation | Number | Yes |
| IdCanal | Channel through which the operation is made. Possible values: 1: Gateway, 2: API (default), 3: Payment Link, 4: Android, 5: iOS | Number | No |
| Email address of the client making the payment | String | Yes | |
| CargosAdicionales | Object with information on additional charges | Object | No |
Response
| Field Name | Description | Type |
|---|---|---|
| Canal | Channel used to process the payment | Number |
| CargosAdicionales | Additional charges details | Object |
| Cuotas | Information about payment installments | Object |
| Descripción | Response providing the transaction status and any additional information | String |
| Exitoso | Indicates if the transaction was successful | Boolean |
| FechaOperacion | Date and time of the transaction | String |
| InfoProceso | Detailed information about the transaction status | Object |
| InfoTarjeta | Credit card details used for payment (if applicable) | Object |
| InfoUsuarioPagador | Information about the customer making the payment | Object |
| MedioDePago | Payment method used | String |
| MerchantId | Merchant's transaction identifier | String |
| Moneda | Currency used for the payment | String |
| Monto | Amount paid | Number |
| MontoOriginal | Information about the original amount (if currency conversion applies) | Object |
| MontoUsd | Value of the amount in U.S. dollars | Number |
| TarjetaHabiente | Payer's details if a card is used | Object |
| TransaccionId | Transaction identifier in Lukapay | Number |
| TransaccionMerchantId | Transaction identifier from the merchant | Number |
| TrazaId | Unique identifier for the transaction in the merchant's database | String |
For more details on the response objects, see Transaction Response.
Example Usage
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": "VAT",
"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": "successful transaction",
"TrazaId": "dc12c15d2cbe",
"Exitoso": true,
"Canal": "API",
"MedioDePago": "Credit",
"MontoOriginal": null,
"MerchantId": null,
"FechaOperacion": null,
"CargosAdicionales": {
"Comision": 0.0,
"OtrosCargos": [
{
"Concepto": "VAT",
"Monto": 1.6
}
],
"TotalCargos": 1.6,
"MonedaCargos": "VES"
}
}
Webhooks for Asynchronous Payments
Our platform validates the payment reference provided by the user in real-time. If the reference is not automatically found, the transaction is marked as "Pending Review" and retried up to 5 times, with attempts every 2 minutes. If it still cannot be found, the transaction is reviewed manually. In such cases, the user is notified via email. In the integration, the Exitoso field will be marked as true, but you must check InfoProceso.EstatusProcesamiento to determine the actual status of the payment: either success (successful) or pending. The final status is sent through a webhook.