Mercantil
Introduction
This document provides the specifications for implementing Mercantil 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.
Change
Facilitates electronic refunds when the payment exceeds the required amount.
Auth for Debit Card Payment
Allows you to obtain the authentication key to pay with a debit card through BNC.
Request
POST {URL}/api/v1/transaccion/mercantil.auth
Headers
Content-Type: application/json
Authorization: Bearer {token}
Request Body
| Field Name | Description | Type | Required |
|---|---|---|---|
| Tarjeta | The card number | String | Yes |
| Cedula | The ID number | String | Yes |
| ClientIdentify | Object with client connection data | Object | No |
ClientIdentify Object Properties
| Field Name | Description | Type | Required |
|---|---|---|---|
| ipaddress | IP address where the connection is made | String | Yes |
| browser_agent | Browser from which the connection is made | String | Yes |
Response
| Field Name | Description | Type |
|---|---|---|
| Exitoso | Indicates if the authentication was successful | Boolean |
| TipoDeAutorizacion | Type of authorization | String |
| InfoAutorizacion | Object with information from Mercantil | Object |
Example Usage
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"
}
Error Codes
| Code | Message |
|---|---|
| 401 | acceso no autorizado |
| 500 | ocurrió un error inesperado |
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/mercantil.paytdd
Headers
Content-Type: application/json
Authorization: Bearer {token}
Request Body
| Field Name | Description | Type | Required |
|---|---|---|---|
| Tarjeta | The card number linked to the authentication | String | Yes |
| Cedula | The ID number linked to the authentication | String | Yes |
| ClientIdentify | Object linked to the authentication | Object | No |
| NombreTarjetaHabiente | Cardholder's name | String | Yes |
| TipodeCuenta | Account type | String | Yes |
| ClaveTelefonica | Phone key | String | Yes |
| FechaExpiracion | Expiration date. Required format mm/yyyy | String | Yes |
| CodigoSeguridad | Security code | String | Yes |
| Monto | Amount | Number | Yes |
| InfoAutorizacion | Object with Mercantil authentication response data | Object | Yes |
| trazaId | Unique trace identifier in the merchant's database. It is recommended to always send. | String | No |
Response
Example Usage
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
}
Credit Card
Allows processing payments with Mercantil's credit card.
Request
POST {URL}/api/v1/transaccion/mercantil.paytdc
Headers
Content-Type: application/json
Authorization: Bearer {token}
userIp: {client's IP address}
Request Body
| Field Name | Description | Type | Required |
|---|---|---|---|
| Cedula | Identification document associated with the debit card to pay | String | Yes |
| Tarjeta | Debit card number | String | Yes |
| IdTraza | Unique identifier for traceability in the merchant's database | String | Yes |
| NombreTarjetaHabiente | Payer's name | String | Yes |
| FechaExpiracion | Expiration date of the debit card. Format: “MM/YYYY” | String | Yes |
| CodigoSeguridad | Security code CVV | String | No |
| 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 |
| Email address of the client making the payment | String | Yes | |
| DireccionIp | IP address from where the connection is made | String | Yes |
| CargosAdicionales | Object with additional charges information | 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": "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"
}
}
Payment C2P
Allows making payments through the C2P modality
Request
POST {URL}/api/v1/transaccion/mercantil.payc2p
Headers
Content-Type: application/json
Authorization: Bearer {token}
userIp: {customer's IP address}
Request Body
| Field Name | Description | Type | Required |
|---|---|---|---|
| TelefonoDestino | Customer payer's phone number | String | Yes |
| CodigoBancoDestino | Bank code of the payer | String | Yes |
| IdTraza | Unique trace identifier in the merchant's database | String | Yes |
| NumeroCedula | Customer payer's ID | String | Yes |
| NombrePagador | Customer payer's name | String | No |
| Monto | Amount of the operation | Number | Yes |
| IdCanal | Channel through which the operation is carried out. Possible values: 1: Gateway, 2: API (default), 3: Payment Link, 4: Android, 5: iOS | Number | No |
| Email address of the customer making the payment | String | Yes | |
| Referencia | Identification of the final customer if required | String | No |
| ClavePago | OTP code | String | Yes |
| DireccionIp | IP address from where the connection is made | 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
{
"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
}
Change
Allows making a P2P transaction from Mercantil bank.
Request
POST {URL}/api/v1/transaccion/mercantil.payp2p.token
Headers
Content-Type: application/json
Authorization: Bearer {token}
Query Params
The following parameters are sent through the query string of the request:
| Name | Type | Description |
|---|---|---|
| userIp | String | IP address from where the connection is made |
| idUsuario | String | Unique identifier of the user |
| String | Email address of the user |
Body
Array of objects with the following structure:
| Field Name | Description | Type | Required |
|---|---|---|---|
| NumeroCedula | Identification document associated with the destination phone | String | Yes |
| TelefonoDestino | Destination phone for the funds | String | Yes |
| Monto | Amount of the operation | Number | Yes |
| CodigoBancoDestino | Destination bank code | String | Yes |
| Descripcion | Description added by the user | String | Yes |
Response
If successful, the response will have a status code of 202. Additionally, an email will be sent to the user who made the transaction with the result of the process.
Examples
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": "P2P Test V1"
},
{
"NumeroCedula": "V6888473",
"TelefonoDestino": "584166227839",
"Monto": 50.99,
"CodigoBancoDestino": "0105",
"Descripcion": "P2P Test V2"
}
]