Bancaribe

Introducción

Este documento proporciona las especificaciones para implementar los métodos de pagos de Bancaribe 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

📄 Transferencia Inmediata

Realiza pagos a través de la modalidad de transferencias inmediatas a proveedores o clientes

Pago Móvil y Transferencia

Realiza pagos a través de la modalidad de pago móvil y transferencia hacia cualquier banco.

Pago C2P

Permite realizar pagos utilizando la modalidad Cliente a Proveedor (C2P).

📄 Vuelto

Facilita la devolución del cambio de manera electrónica cuando el pago excede el monto requerido.

Transferencia Inmediata

Permite a los comercios la posibilidad de realizar pagos a proveedores o clientes a través de la modalidad de transferencias hacia cualquier banco nacional.

Request

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

Headers

Content-Type: application/json
Authorization: Bearer {token}
userIp: {dirección IP del cliente}

Body

Nombre del campo	Descripción	Tipo	Obligatorio
browserAgent	Navegador web donde se realiza la consulta	String	Sí
cuentaDestino	Número de cuenta o teléfono destino de los fondos	String	Sí
bancoDestino	Código del banco destino de los fondos	String	Sí
idTraza	Identificador único de trazabilidad en la base de datos del comercio	String	Sí
cedulaBeneficiario	Documento de identificación del cliente natural o jurídico beneficiario de los fondos	String	Sí
nombreBeneficiario	Nombre del beneficiario de los fondos	String	Sí
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
referencia	Identificación del cliente final en caso de que se requiera	String	No
email	Dirección de correo electrónico del cliente que realiza el pago	String	Sí

Response

Body

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

{
    "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
}

Pago Móvil y Transferencia

Permite validar y registrar un pago realizado a través de la modalidad de pago móvil y transferencia.

Request

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

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 de 4 dígitos del banco	String	Sí
telefonoPagador	Número de teléfono desde donde se realizó el pago móvil.	String	Sí
cedulaPagador	Cédula de identidad del cliente	String	No
numeroReferencia	Código de autorización del pago móvil o transferencia.	String	Sí
monto	Monto de la operación	Number	Sí
email	Correo electrónico del cliente	String	Sí
referencia	Valor opcional que permite identificar algo relacionado con el pago	String	No
idTraza	Identificador único de trazabilidad en la base de datos del comercio.	String	Sí
idCanal	Canal por donde realiza la operación.	Number	No
tipoTransaccion	Indica el tipo de transacción. "PM": Pago Móvil, "TRF": Transferencia	String	Sí

Response

Body

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

{
  "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

El movimiento se validó efectivamente y se registra.

{
  "Monto": 1.03,
  "MontoUsd": 0.0,
  "InfoProceso": {
    "EstatusProcesamiento": "success",
    "CodigoRespuestaCvv": null
  },
  "TarjetaHabiente": null,
  "InfoUsuarioPagador": {
    "Nombre": "Pedro",
    "Apellido": "Perez",
    "NumeroIdentidad": "V12345678",
    "NumeroTelefono": "04141232233",
    "Email": "email@example.com"
  },
  "Moneda": "VES",
  "InfoTarjeta": null,
  "TransaccionId": 101935,
  "TransaccionMerchantId": 101935,
  "Descripcion": "transacción exitosa",
  "TrazaId": "aedda81a8aee",
  "Exitoso": true,
  "Canal": "Pasarela de pago",
  "MedioDePago": "Transferencia",
  "MontoOriginal": null,
  "MerchantId": "30867220134",
  "FechaOperacion": "05/07/2024 19:23:20",
  "CargosAdicionales": null,
  "Cuotas": null
}

Pending

El movimiento no se validó, se registra como pendiente.

note

Para ver más sobre pagos pendientes, ver Webhooks: Pagos diferidos.

Error: Pago Registrado

El mismo pago ya fue validado y registrado anteriormente.

{
    "Codigo": 400,
    "Mensaje": "el pago ya fue registrado",
    "Continua": false
}

Pago C2P

Permite realizar pago a través de la modalidad C2P

Request

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

Headers

Content-Type: application/json
Authorization: Bearer {token}
userIp: {dirección IP del cliente}

Request Body

Nombre del campo	Descripción	Tipo	Obligatorio
browserAgent	Navegador web donde se realiza la consulta	String	Sí
cuentaDestino	Teléfono del cliente pagador	String	Sí
bancoDestino	Código del Banco Pagador	String	Sí
idTraza	Identificador único de trazabilidad en la base de datos del comercio	String	Sí
cedulaBeneficiario	Cedula del cliente pagador	String	Sí
nombreBeneficiario	Nombre del cliente pagador	String	Sí
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
email	Dirección de correo electrónico del cliente que realiza el pago	String	Sí
Referencia	Identificación del cliente final en caso de que se requiera	String	No
claveTemporal	Código OTP	String	Sí

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

{
    "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": "Transacción exitosa",
  "TrazaId": "1362c6e9f67e",
  "Exitoso": true,
  "MedioDePago": "C2P",
  "Canal": "API",
  "MontoOriginal": null,
  "MerchantId": "30867220134",
  "FechaOperacion": "05/07/2024 19:23:20",
  "CargosAdicionales": null,
  "Cuotas": null
}

Vuelto

En proceso de documentación.

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.

Ver más sobre webhooks.