Skip to main content
All Mercantil functions forward requests to the Mercantil API Gateway (apimbu.mercantilbanco.com) using the configured X-IBM-Client-ID. Sensitive fields (CVV, national ID, phone numbers) are AES-256 encrypted before transmission. All request bodies use the data envelope.

​
api_mercantil_auth

POST https://{region}-{project}.cloudfunctions.net/api_mercantil_auth
Requests a debit card (TDD) authorization token from Mercantil. Must be called before api_mercantil_tdd_pay to obtain the twofactor_auth OTP challenge. Forwards to: POST https://apimbu.mercantilbanco.com/mercantil-banco/prod/v1/payment/getauth

​
Request body

​
data.customer_id
string
required
Cardholder national ID (cédula). Sent as-is (not encrypted at this step).
​
data.card_number
string
required
Debit card number.
​
data.ipaddress
string
required
Client IP address, forwarded to Mercantil for fraud detection.

​
Response

​
status
number
200 on success, 400 on Mercantil error.
​
data
object
Raw response object from the Mercantil getauth endpoint.

​
Example

curl -X POST \
  https://{region}-{project}.cloudfunctions.net/api_mercantil_auth \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "customer_id": "12345678",
      "card_number": "4111111111111111",
      "ipaddress": "190.0.0.1"
    }
  }'

​
api_mercantil_tdd_pay

POST https://{region}-{project}.cloudfunctions.net/api_mercantil_tdd_pay
Processes a purchase with a Mercantil debit card (Tarjeta de Débito). CVV and the two-factor OTP are AES-256 encrypted before forwarding to Mercantil. Forwards to: POST https://apimbu.mercantilbanco.com/mercantil-banco/prod/v1/payment/pay with payment_method: "tdd"

​
Request body

​
data.amount
number
required
Transaction amount in VES (bolívares).
​
data.invoice_number
string
required
Unique invoice/order number for idempotency.
​
data.customer_id
string
required
Cardholder national ID (cédula).
​
data.card_number
string
required
Debit card number.
​
data.cvv
string
required
Card verification value. Encrypted with AES-256 before sending to Mercantil.
​
data.expiration_date
string
required
Card expiration date in the format accepted by Mercantil (e.g. "MM/YY").
​
data.account_type
string
required
Mercantil account type code (e.g. "CC" for current, "CA" for savings).
​
data.twofactor_auth
string
required
OTP/two-factor code obtained from api_mercantil_auth. Encrypted with AES-256 before sending.
​
data.ipaddress
string
required
Client IP address.

​
Response

​
message
string
"Procesado" on success, "Error" on failure.
​
data
object
Raw response object from the Mercantil payment endpoint.

​
Example

curl -X POST \
  https://{region}-{project}.cloudfunctions.net/api_mercantil_tdd_pay \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "amount": 1825.00,
      "invoice_number": "INV-2026-001",
      "customer_id": "12345678",
      "card_number": "4111111111111111",
      "cvv": "123",
      "expiration_date": "12/27",
      "account_type": "CA",
      "twofactor_auth": "456789",
      "ipaddress": "190.0.0.1"
    }
  }'

​
api_mercantil_tdc_pay

POST https://{region}-{project}.cloudfunctions.net/api_mercantil_tdc_pay
Processes a purchase with a Mercantil credit card (Tarjeta de Crédito). CVV is AES-256 encrypted before forwarding. Unlike the debit flow, no account_type or twofactor_auth is required. Forwards to: POST https://apimbu.mercantilbanco.com/mercantil-banco/prod/v1/payment/pay with payment_method: "tdc"

​
Request body

​
data.amount
number
required
Transaction amount in VES.
​
data.invoice_number
string
required
Unique invoice/order number.
​
data.customer_id
string
required
Cardholder national ID (cédula).
​
data.card_number
string
required
Credit card number.
​
data.cvv
string
required
Card verification value. AES-256 encrypted before forwarding.
​
data.expiration_date
string
required
Card expiration date.
​
data.ipaddress
string
required
Client IP address.

​
Response

​
message
string
"Procesado" on success, "Error" on failure.
​
data
object
Raw response object from the Mercantil payment endpoint.

​
Example

curl -X POST \
  https://{region}-{project}.cloudfunctions.net/api_mercantil_tdc_pay \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "amount": 1825.00,
      "invoice_number": "INV-2026-002",
      "customer_id": "12345678",
      "card_number": "5111111111111118",
      "cvv": "321",
      "expiration_date": "06/28",
      "ipaddress": "190.0.0.1"
    }
  }'

​
api_mercantil_c2p_auth

POST https://{region}-{project}.cloudfunctions.net/api_mercantil_c2p_auth
Initiates a Pago Móvil C2P (Cobro a un Pagador) authorization flow. destination_id and destination_mobile_number are AES-256 encrypted before forwarding. This call registers the merchant’s intent to charge a payer via mobile payment. Forwards to: POST https://apimbu.mercantilbanco.com/mercantil-banco/sandbox/v1/mobile-payment/scp

​
Request body

​
data.destination_id
string
required
National ID (cédula) of the payment destination (merchant). AES-256 encrypted before forwarding.
​
data.destination_mobile_number
string
required
Merchant mobile phone number registered for Pago Móvil. AES-256 encrypted before forwarding.
​
data.ipaddress
string
required
Client IP address.

​
Response

​
message
string
"Procesado" on success, "Error" on failure.
​
data
object
Raw response from the Mercantil SCP endpoint.

​
api_mercantil_c2p_pay

POST https://{region}-{project}.cloudfunctions.net/api_mercantil_c2p_pay
Executes a Pago Móvil C2P (Compra) charge. The payer’s national ID, destination and origin phone numbers, and the two-factor OTP are all AES-256 encrypted before forwarding to Mercantil. Forwards to: POST https://apimbu.mercantilbanco.com/mercantil-banco/prod/v1/payment/c2p

​
Request body

​
data.amount
number
required
Transaction amount in VES.
​
data.invoice_number
string
required
Unique invoice/order number.
​
data.destination_bank_id
string
required
Bank code of the destination (merchant) bank, e.g. "0105" for Mercantil.
​
data.destination_id
string
required
National ID of the payment destination. AES-256 encrypted before forwarding.
​
data.destination_mobile_number
string
required
Destination (merchant) mobile number for Pago Móvil. AES-256 encrypted before forwarding.
​
data.origin_mobile_number
string
required
Payer’s mobile number. AES-256 encrypted before forwarding.
​
data.payment_reference
string
required
A reference string provided by the payer’s bank to identify the transaction.
​
data.twofactor_auth
string
required
OTP code from the payer. AES-256 encrypted before forwarding.
​
data.ipaddress
string
required
Client IP address.

​
Response

​
message
string
"Procesado" on success, "Error" on failure.
​
data
object
Raw response from the Mercantil C2P endpoint.

​
Example

curl -X POST \
  https://{region}-{project}.cloudfunctions.net/api_mercantil_c2p_pay \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "amount": 1825.00,
      "invoice_number": "INV-2026-003",
      "destination_bank_id": "0105",
      "destination_id": "12345678",
      "destination_mobile_number": "04241234567",
      "origin_mobile_number": "04169876543",
      "payment_reference": "REF-123456",
      "twofactor_auth": "789012",
      "ipaddress": "190.0.0.1"
    }
  }'

POST https://{region}-{project}.cloudfunctions.net/api_mercantil_c2p_search
Searches for Pago Móvil transactions in the Mercantil system by mobile numbers, reference, amount, and date. Use this for payment verification before calling order_created. Forwards to: POST https://apimbu.mercantilbanco.com/mercantil-banco/prod/v1/mobile-payment/search

​
Request body

​
data.destination_mobile_number
string
required
Destination mobile number to search. AES-256 encrypted before forwarding.
​
data.origin_mobile_number
string
required
Payer mobile number to search. AES-256 encrypted before forwarding.
​
data.payment_reference
string
required
Reference number to match.
​
data.amount
number
required
Expected transaction amount in VES.
​
data.date_pay
string
required
Transaction date to search, in the format accepted by Mercantil (e.g. "YYYYMMDD").
​
data.ipaddress
string
required
Client IP address.

​
Response

​
message
string
"Procesado" on success, "Error" on failure.
​
data
array
Array of matching transaction objects from Mercantil’s transaction_list.

​
Example

curl -X POST \
  https://{region}-{project}.cloudfunctions.net/api_mercantil_c2p_search \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "destination_mobile_number": "04241234567",
      "origin_mobile_number": "04169876543",
      "payment_reference": "REF-123456",
      "amount": 1825.00,
      "date_pay": "20260319",
      "ipaddress": "190.0.0.1"
    }
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us