Bancaribe

Introduction

This document provides the specifications for implementing Bancaribe 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

Instant Transfer

Make payments via instant transfers to suppliers or customers.

Mobile Payment and Transfer

Make payments through mobile payments and transfers to any bank.

📄 C2P Payment

Allows payments using the Client to Provider (C2P) method.

Change

Facilitates electronic refunds when the payment exceeds the required amount.

Immediate Transfer

Allows merchants to make payments to suppliers or customers through transfers to any national bank.

Request

POST {URL}/api/v1/transaccion/bancaribe.transferencia

Headers

Content-Type: application/json
Authorization: Bearer {token}
userIp: {client's IP address}

Body

Field Name	Description	Type	Required
browserAgent	Web browser used for the request	String	Yes
cuentaDestino	Account number or phone number of the transfer recipient	String	Yes
bancoDestino	Destination bank code	String	Yes
idTraza	Unique trace identifier in the merchant's database	String	Yes
cedulaBeneficiario	Identification document of the individual or legal entity receiving the funds	String	Yes
nombreBeneficiario	Name of the recipient	String	Yes
monto	Amount of the transaction	Number	Yes
idCanal	Channel through which the transaction is made. Possible values: 1: Gateway, 2: API (default), 3: Payment Link, 4: Android, 5: iOS	Number	No
referencia	Final customer's reference, if required	String	No
email	Customer's email address	String	Yes

Response

Body

Field Name	Description	Type
Canal	Indicates the channel being used for the payment in Lukapay	Number
CargosAdicionales	Object containing additional charges	Object
Cuotas	Object containing installment information	Object
Descripción	Contains the payment response, including transaction status and additional information	String
Exitoso	Indicates whether the transaction was successful	Boolean
FechaOperacion	Date of the transaction	String
InfoProceso	Object with detailed status information of the transaction	Object
InfoTarjeta	Object containing credit card information used for the payment (only applies to credit card payments)	Object
InfoUsuarioPagador	Object returning basic information of the paying user	Object
MedioDePago	Indicates the payment method used	String
MerchantId	Merchant transaction reference used for the payment	String
Moneda	Currency code used for the payment	String
Monto	Indicates the payment amount	Number
MontoOriginal	Object with information on the original amount, used if a currency conversion is applied	Object
MontoUsd	Amount value in US dollars, used when MontoOriginal is specified	Number
TarjetaHabiente	Object containing payer information (if specified)	Object
TransaccionId	Lukapay transaction reference	Number
TransaccionMerchantId	Merchant transaction reference used for the payment	Number
TrazaId	Merchant's internal identifier; if not provided, a random code is generated	String

Object attributes are specified in Transaction Response.

Usage Example

Request Body

{
    "BancoDestino": "0114",
    "CedulaBeneficiario": "V1234567",
    "CuentaDestino": "01140111111112222222",
    "BrowserAgent": "Chrome",
    "Monto": 16.03,
    "NombreBeneficiario": "Pedro Perez",
    "IdTraza": "1362c6e9f67e",
    "idCanal": 1,
    "Referencia": "",
    "Email": "demo@example.com"
}

Response Body

{
  "Monto": 16.03,
  "MontoUsd": 0,
  "InfoProceso": {
    "EstatusProcesamiento": "success"
  },
  "TarjetaHabiente": null,
  "Moneda": "VES",
  "InfoTarjeta": null,
  "InfoUsuarioPagador": {
    "Nombre": "Pedro",
    "Apellido": "Perez",
    "Email": "demo@example.com"
  },
  "TransaccionId": 11339,
  "MerchantId": 516458,
  "Descripcion": "Transacción exitosa",
  "TrazaId": "1362c6e9f67e",
  "Exitoso": true,
  "MedioDePago": "Transferencia",
  "Canal": "API",
  "MontoOriginal": null,
  "MerchantId": "30867220134",
  "FechaOperacion": "05/07/2024 19:23:20",
  "CargosAdicionales": null,
  "Cuotas": null
}

Mobile Payment and Transfer

Allows the validation and registration of a payment made via mobile payment and transfer.

Request

POST {URL}/api/v1/transaccion/bancaribe.consulta

Headers

Content-Type: application/json
Authorization: Bearer {token}
userIp: {client's IP address}

Body

Field Name	Description	Type	Required
nombrePagador	Payer's name	String	No
codigoBancoPagador	Payer's bank code (4 digits)	String	Yes
telefonoPagador	Payer's mobile phone number	String	Yes
cedulaPagador	Payer's ID	String	No
numeroReferencia	Mobile payment or transfer authorization code	String	Yes
monto	Transaction amount	Number	Yes
email	Payer's email	String	Yes
referencia	Optional value to identify something related to the payment	String	No
idTraza	Unique trace identifier in the merchant's database	String	Yes
idCanal	Channel through which the transaction is made	Number	No
tipoTransaccion	Transaction type. "PM": Mobile Payment, "TRF": Transfer	String	Yes

Response

Body

Field Name	Description	Type
Canal	Indicates the channel being used for the payment in Lukapay	Number
CargosAdicionales	Object containing additional charges	Object
Cuotas	Object containing installment information	Object
Descripción	Contains the payment response, including transaction status and additional information	String
Exitoso	Indicates whether the transaction was successful	Boolean
FechaOperacion	Date of the transaction	String
InfoProceso	Object with detailed status information of the transaction	Object
InfoTarjeta	Object containing credit card information used for the payment (only applies to credit card payments)	Object
InfoUsuarioPagador	Object returning basic information of the paying user	Object
MedioDePago	Indicates the payment method used	String
MerchantId	Merchant transaction reference used for the payment	String
Moneda	Currency code used for the payment	String
Monto	Indicates the payment amount	Number
MontoOriginal	Object with information on the original amount, used if a currency conversion is applied	Object
MontoUsd	Amount value in US dollars, used when MontoOriginal is specified	Number
TarjetaHabiente	Object containing payer information (if specified)	Object
TransaccionId	Lukapay transaction reference	Number
TransaccionMerchantId	Merchant transaction reference used for the payment	Number
TrazaId	Merchant's internal identifier; if not provided, a random code is generated	String

Object attributes are specified in Transaction Response.

Usage Example

Request body

{
  "nombrePagador": "Pedro Perez",
  "codigoBancoPagador": "0105",
  "telefonoPagador": "04125555555",
  "cedulaPagador": "V12345678",
  "numeroReferencia": "30867220134",
  "monto": 1.0,
  "email": "email@example.com",
  "referencia": "",
  "idTraza": "aedda81a8aee",
  "idCanal": 1,
  "numeroFactura": "null",
  "tipoTransaccion": "PM"
}

Response body

Success

The payment was validated and registered successfully.

{
  "Monto": 1.03,
  "MontoUsd": 0.0,
  "InfoProceso": {
    "EstatusProcesamiento": "success",
    "CodigoRespuestaCvv": null
  },
  "TarjetaHabiente": null,
  "InfoUsuarioPagador": {
    "Nombre": "Pedro",
    "Apellido": "Perez",
    "NumeroIdentidad": "V

12345678",
    "Email": "email@example.com"
  },
  "TransaccionId": 2000000,
  "MerchantId": 516458,
  "Descripcion": "Transacción exitosa",
  "TrazaId": "aedda81a8aee",
  "Exitoso": true,
  "MedioDePago": "Transferencia",
  "Canal": "API",
  "MontoOriginal": null,
  "MerchantId": "30867220134",
  "FechaOperacion": "23/07/2024 19:23:20",
  "CargosAdicionales": null,
  "Cuotas": null
}

Pending

The transaction was not validated and is recorded as pending.

note

For more information on pending payments, see Webhooks: Asynchronous Payments.

Error: Payment Registered

The same payment has already been validated and recorded previously.

{
    "Code": 400,
    "Message": "the payment has already been registered",
    "Continue": false
}

C2P Payment

Allows to make payments using the C2P method, enabling customers to pay using their bank account.

Request

POST {URL}/api/v1/transaccion/bancaribe.c2p

Headers

Content-Type: application/json
Authorization: Bearer {token}
userIp: {client's IP address}

Request Body

Field Name	Description	Type	Required
browserAgent	Web browser used by the customer	String	Yes
cuentaDestino	Customer's phone number	String	Yes
bancoDestino	Payer's bank code	String	Yes
idTraza	Unique transaction identifier in the merchant's database	String	Yes
cedulaBeneficiario	Payer's ID	String	Yes
nombreBeneficiario	Payer's name	String	Yes
monto	Transaction amount	Number	Yes
idCanal	Transaction channel. Possible values: 1 (Gateway), 2 (API), 3 (Payment Link), 4 (Android), 5 (iOS)	Number	No
email	Email address of the customer making the payment	String	Yes
referencia	Customer identifier if needed	String	No
claveTemporal	OTP (One-Time Password)	String	Yes

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

{
    "bancoDestino": "0114",
    "cedulaBeneficiario": "V1234567",
    "cuentaDestino": "01140111111112222222",
    "browserAgent": "Chrome",
    "monto": 16.03,
    "nombreBeneficiario": "Pedro Perez",
    "idTraza": "1362c6e9f67e",
    "idCanal": 1,
    "email": "demo@example.com",
    "claveTemporal": "15487898"
}

Response Body

{
  "Monto": 16.03,
  "MontoUsd": 0,
  "InfoProceso": {
    "EstatusProcesamiento": "success"
  },
  "TarjetaHabiente": null,
  "Moneda": "VES",
  "InfoTarjeta": null,
  "InfoUsuarioPagador": {
    "Nombre": "Pedro",
    "Apellido": "Perez",
    "Email": "demo@example.com"
  },
  "TransaccionId": 11339,
  "MerchantId": 516458,
  "Descripcion": "Transaction successful",
  "TrazaId": "1362c6e9f67e",
  "Exitoso": true,
  "MedioDePago": "C2P",
  "Canal": "API",
  "MontoOriginal": null,
  "MerchantId": "30867220134",
  "FechaOperacion": "05/07/2024 19:23:20",
  "CargosAdicionales": null,
  "Cuotas": null
}

Change

Work in progress.

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.

Learn more about webhooks.