Mercantil

Introducción

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

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

📄 Tarjeta de Débito

Realiza pagos con tu tarjeta de débito.

📄 Tarjeta de Crédito

Realiza pagos con tu tarjeta de crédito.

📄 Vuelto

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

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/mercantil.auth

Headers

Content-Type: application/json
Authorization: Bearer {token}

Body

Nombre del campo	Descripción	Tipo	Obligatorio
Tarjeta	El número de tarjeta	String	Sí
Cedula	El número de cédula	String	Sí
ClientIdentify	Objeto con datos de la conexión de cliente	Object	No

Propiedad del objeto ClientIdentify

Nombre del campo	Descripción	Tipo	Obligatorio
ipaddress	Dirección IP de donde se realiza la conexión	String	Sí
browser_agent	Navegador de donde se realiza la conexión	String	Sí

Response

Nombre	Descripción	Tipo
Exitoso	Indica si la autenticación fue exitosa	Boolean
TipoDeAutorizacion	Tipo de autorización	String
InfoAutorización	Objeto con información de la información devuelto por Mercantil	Object

Ejemplo de uso

Request body

{
  "Tarjeta": "501878200066287386",
  "Cedula": "18366876",
  "ClientIdentify": {
    "ipaddress": "127.0.0.1",
    "browser_agent": "Chrome 18.1.3"
  }
}

Response body

Success

{
  "Exitoso": true,
  "TipoDeAutorizacion": "opt",
  "InfoAutorizacion": {
    "procesing_date": null,
    "trx_status": "approved",
    "trx_type": "solaut",
    "payment_method": "tdd",
    "twofactor_type": "4tKfujuhjjd89sdjh=="
  }
}

Failed

{
   "errorauth": "Numero de tarjeta incorrecto"
}

Códigos de Error

Código	Mensaje
401	acceso no autorizado
500	ocurrió un error inesperado

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/mercantil.paytdd

Headers

Content-Type: application/json
Authorization: Bearer {token}

Body

Nombre del campo	Descripción	Tipo	Obligatorio
Tarjeta	El número de tarjeta vinculado al iniciar la autenticación	String	Sí
Cedula	El número de cédula vinculado al iniciar la autenticación	String	Sí
ClientIdentify	Objeto vinculado al iniciar la autenticación	Object	No
NombreTarjetaHabiente	Nombre del TarjetaHabiente	String	Sí
TipodeCuenta	Tipo de Cuenta	String	Sí
ClaveTelefonica	Clave Telefónica	String	Sí
FechaExpiracion	Fecha de expiración. Formato requerido mm/yyyy	String	Sí
CodigoSeguridad	Código de Seguridad	String	Sí
Monto	Monto	Number	Sí
InfoAutorizacion	Objeto MercantilAuthtddResponse	Object	Sí
trazaId	Identificador único de trazabilidad en la base de datos del comercio. Se recomienda enviar siempre.	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

{
  "Tarjeta": "501878200066287386",
  "Cedula": "18366876",
  "ClientIdentify": {
    "ipaddress": "127.0.0.1",
    "browser_agent": "Chrome 18.1.3"
  },
  "NombreTarjetaHabiente": "Adquiriente",
  "TipodeCuenta": "ahorro",
  "ClaveTelefonica": "11111111",
  "FechaExpiracion": "03/2022",
  "CodigoSeguridad": "563",
  "Monto": 1,
  "InfoAutorizacion": {
    "authentication_info": {
      "procesing_date": null,
      "trx_status": "approved",
      "trx_type": "solaut",
      "payment_method": "tdd",
      "twofactor_type": "4tKooo0HYTEV45jHHJ=="
    },
    "merchant_identify": {
      "integratorId": 200292,
      "merchantId": 200292,
      "terminalId": "apipayco"
    }
  }
}

Response body

Success

{
  "Monto":1,
  "MontoUsd":0,
  "InfoProceso":null,
  "TarjetaHabiente":{
     "Apellido":"Perez",
     "LukapayId":null,
     "Nombre":"Pedro",
     "NumeroIdentificacionPersonal":null,
     "NumeroTelefono":null
  },
  "InfoUsuarioPagador":null,
  "Moneda":"VES",
  "InfoTarjeta":{
     "Bin":"501800",
     "CategoriaTarjeta":null,
     "Ciudad":null,
     "CodigoPostal":null,
     "Descripcion":null,
     "Direccion":null,
     "EstaBoveda":false,
     "Estado":null,
     "FechaVencimiento":"02/2023",
     "Id":0,
     "IdStatus":0,
     "Moneda":null,
     "Pais":null,
     "SubTipoTarjeta":null,
     "TipoTarjeta":null
  },
  "TransaccionId":90005,
  "TransaccionMerchantId":90005,
  "Descripcion":"transacción exitosa",
  "TrazaId":"9b2nnn1b-326n-436n-8hnf-0a000oklcf3h9",
  "Exitoso":true,
  "Canal":"Api",
  "MedioDePago":"Débito",
  "MontoOriginal":null,
  "MerchantId":null,
  "FechaOperacion":"2023-04-01 13:36:47.588913+00:00",
  "CargosAdicionales":null
}

Failed

{
  "Monto":1,
  "MontoUsd":0,
  "InfoProceso":null,
  "TarjetaHabiente":null,
  "InfoUsuarioPagador":null,
  "Moneda":"VES",
  "InfoTarjeta":null,
  "TransaccionId":90005,
  "TransaccionMerchantId":0,
  "Descripcion":"Cliente informado no es titular del medio de pago",
  "TrazaId":"9b2nnn1b-326n-436n-8hnf-0a000oklcf3h9",
  "Exitoso":false,
  "Canal":"Api",
  "MedioDePago":"Débito",
  "MontoOriginal":null,
  "MerchantId":null,
  "FechaOperacion":"2023-04-01 13:36:47.588913+00:00",
  "CargosAdicionales":null
}

Tarjeta de crédito

Permite procesar pago con la tarjeta de crédito de mercantil.

Request

POST {URL}/api/v1/transaccion/mercantil.paytdc

Headers

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

Request 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
Email	Dirección de correo electrónico del cliente que realiza el pago	String	Sí
DireccionIp	Dirección IP de donde se realiza la conexión	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.

Ejemplos 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": "demo@example.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"
  }
}

Pago C2P

Permite realizar pago a través de la modalidad C2P

Request

POST {URL}/api/v1/transaccion/mercantil.payc2p

Headers

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

Request Body

Nombre del campo	Descripción	Tipo	Obligatorio
TelefonoDestino	Teléfono del cliente pagador	String	Sí
CodigoBancoDestino	Código del Banco Pagador	String	Sí
IdTraza	Identificador único de trazabilidad en la base de datos del comercio	String	Sí
NumeroCedula	Cedula del cliente pagador	String	Sí
NombrePagador	Nombre del cliente pagador	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
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
ClavePago	Código OTP	String	Sí
DireccionIp	Dirección IP de donde se realiza la conexión	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

{
    "Email": "demo@example.com",
    "DireccionIp": "1.1.1.1",
    "ClavePago": "12345678",
    "Monto": 10,
    "CodigoBancoDestino": "0123",
    "NumeroCedula": "V123456789",
    "TelefonoDestino": "584121234567",
    "Link": null,
    "Referencia": null,
    "IdTraza": "2a5da8b19622",
    "IdCanal": 2,
    "NombrePagador": "Pedro Perez",
    "MontoOriginal": null,
    "CargosAdicionales": null
}

Response Body

{
  "Monto": 10.0,
  "MontoUsd": 0.0,
  "InfoProceso": null,
  "TarjetaHabiente": null,
  "InfoUsuarioPagador": {
    "Nombre": "Pedro",
    "Apellido": "Perez",
    "NumeroIdentidad": "V123456789",
    "NumeroTelefono": "584121234567",
    "Email": "demo@example.com"
  },
  "Moneda": "VES",
  "InfoTarjeta": null,
  "TransaccionId": 102638,
  "TransaccionMerchantId": 102638,
  "Descripcion": "transacción exitosa",
  "TrazaId": "2a5da8b19622",
  "Exitoso": true,
  "Canal": "Api",
  "MedioDePago": "C2P",
  "MontoOriginal": null,
  "MerchantId": null,
  "FechaOperacion": null,
  "CargosAdicionales": null,
  "Cuotas": null
}

Vuelto

Permite realizar una transacción P2P desde el banco Mercantil.

Request

POST {URL}/api/v1/transaccion/mercantil.payp2p.token

Headers

Content-Type: application/json
Authorization: Bearer {token}

Query Params

Los siguientes parámetros se envían a través del querystring del a consulta

Nombre	Tipo	Descripción
userIp	String	Dirección IP de donde se realiza la conexión
idUsuario	String	Identificador único del usuario.
email	String	Dirección de correo electrónico del usuario

Body

Array de objetos con la siguiente estructura:

Nombre del campo	Descripción	Tipo	Obligatorio
NumeroCedula	Documento de identificación asociada al teléfono destino	String	Sí
TelefonoDestino	Teléfono destino de los fondos	String	Sí
Monto	Monto de la operación	Number	Sí
CodigoBancoDestino	Código del banco destino	String	Sí
Descripcion	Descripción agregada por el usuario	String	Sí

Response

En caso de ser exitosa la respuesta, tendrá un status code de 202. Además, se le enviará un correo electrónico al usuario que hizo la operación con el resultado del proceso.

Ejemplos de uso

Request

{URL}/api/v1/transaccion/mercantil.payp2p.token?userIp=1.1.1.1&idUsuario=123&email=demo@lukapay.io

Request body

[
    {
        "NumeroCedula": "V6888473",
        "TelefonoDestino": "584166227839",
        "Monto": 12.00,
        "CodigoBancoDestino": "0105",
        "Descripcion": "Prueba P2P V1"
    },
    {
        "NumeroCedula": "V6888473",
        "TelefonoDestino": "584166227839",
        "Monto": 50.99,
        "CodigoBancoDestino": "0105",
        "Descripcion": "Prueba P2P V2"
    }
]

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.