POST /api/v1/payments/pagar-mercado-pago

The Mercado Pago payment endpoints provide the same hotspot-provisioning experience as the Conekta flow, but using Mercado Pago as the payment processor. The frontend tokenizes card data using the Mercado Pago JS SDK and submits the resulting token along with card metadata to this endpoint. The server creates the MikroTik hotspot user first, then charges the card — rolling back the user if the charge fails. On success, optional Telegram notifications can be sent to the operator’s configured chat.

Endpoints

Method	Path	Description
`POST`	`/api/v1/payments/pagar-mercado-pago`	Process a Mercado Pago card payment and provision hotspot access
`GET`	`/api/v1/payments/estado-pago/{payment_id}`	Check the current status of a Mercado Pago payment by its ID

Headers

X-API-Key

string

required

Router API Key in the format jwt_<token>. Identifies the company (which must have a configured Mercado Pago access token) and the target MikroTik router.

Body

The request body accepts both canonical field names and their Spanish aliases. Both forms are valid.

producto_id

integer

required

ID of the product to purchase. Obtain from GET /api/v1/catalogo_perfiles_venta. Also accepted as product_id.

token

string

required

Card token generated by the Mercado Pago JS SDK (mp.createCardToken). Single-use; expires shortly after creation.

payment_method_id

string

required

Mercado Pago payment method identifier returned by the SDK when the card is detected. Examples: "visa", "master", "amex".

monto

float

required

Transaction amount in the product’s currency. Also accepted as transaction_amount.

This value must exactly match the product’s precio field (tolerance ±0.01). If the amounts differ, the server returns HTTP 400 with a mismatch error before any MikroTik user is created or any charge is attempted. Always read the price from the catalog endpoint and pass it back unchanged.

email_cliente

string

required

Customer’s email address. Passed to Mercado Pago as the payer email. Must be a valid email format. Also accepted as customer_email.

nombre_cliente

string

required

Full name of the customer. Stored in the transaction record and included in Telegram notifications. Also accepted as customer_name.

issuer_id

string

Card issuer (bank) ID returned by the Mercado Pago SDK. Optional but recommended for improved approval rates.

cuotas

integer

default:"1"

Number of installments for the payment. Pass 1 for a single full charge. Also accepted as installments.

telefono_cliente

string

Customer phone number. Optional. Also accepted as customer_phone.

device_id

string

Mercado Pago device fingerprint ID, obtained from mp.getIdentificationTypes() or the MP_DEVICE_SESSION_ID cookie. Helps reduce fraud rejections.

payer

object

Additional payer information object to pass directly to the Mercado Pago API. If not provided, the server constructs a minimal payer with {"email": customer_email}. Useful for supplying identification type/number when required by the country’s regulations.

{
  "email": "[email protected]",
  "identification": {
    "type": "RFC",
    "number": "PEPJ901231..."
  }
}

tipo_usuario

string

default:"usuario_contrasena"

Type of hotspot credentials to generate. Also accepted as user_type.

"usuario_contrasena" — (default) Username + password pair.
"pin" — Single 6-digit numeric PIN (empty password).

mac_cliente

string

MAC address of the client device. Required for auto-connection. Also accepted as mac_address.

ip_cliente

string

Current IP of the client device. Used during auto-connection. Also accepted as ip_address.

conexion_automatica

boolean

default:"false"

When true, attempts to auto-authenticate the device on MikroTik after a successful payment. Requires mac_cliente. Also accepted as auto_connect.

Response

On success the endpoint returns HTTP 200.

success

boolean

Always true on success.

id_transaccion

string

Mercado Pago payment ID (numeric, stored as string). Use this for GET /api/v1/payments/estado-pago/{payment_id}.

estado_pago

string

Mercado Pago payment status. "approved" for successful instant payments. May be "pending" in some cases (see advertencia field).

tipo_usuario

string

The user type used to generate credentials: "usuario_contrasena" or "pin".

usuario_hotspot

object

WiFi credentials to display to the customer.

Show usuario_hotspot fields

usuario_hotspot.usuario

string

Hotspot username (alphanumeric for usuario_contrasena, 6-digit PIN for pin type).

usuario_hotspot.contrasena

string

Hotspot password. Empty string "" for pin type.

producto

object

Purchased product summary.

Show producto fields

producto.nombre

string

Product name.

producto.precio

float

Price that was charged.

producto.moneda

string

Currency code (e.g., "MXN").

producto.perfil_mikrotik

string

MikroTik profile applied to the created hotspot user.

cliente

object

Customer information from the request.

Show cliente fields

cliente.nombre

string

Customer name.

cliente.email

string

Customer email.

mercado_pago

object

Mercado Pago-specific payment details.

Show mercado_pago fields

mercado_pago.payment_id

string | integer

Mercado Pago’s unique payment identifier.

mercado_pago.status

string

Raw payment status from Mercado Pago (e.g., "approved", "pending").

mercado_pago.status_detail

string

Detailed status code from Mercado Pago (e.g., "accredited", "pending_contingency"). Useful for debugging declined payments.

mercado_pago.installments

integer

Number of installments for this payment, as submitted.

mercado_pago.payment_method

object

Payment method object returned by Mercado Pago. Contains card type, brand, and last four digits.

mercado_pago.raw_response

object

Full raw response from Mercado Pago’s payment API. Useful for debugging. Do not display to end users.

timestamp

string

ISO 8601 UTC datetime of transaction completion.

auto_conexion

object

Auto-connection result. Same structure as the Conekta endpoint.

Show auto_conexion fields

auto_conexion.estado

string

"conectado" or "no_conectado".

auto_conexion.mac

string

MAC address used in the connection attempt.

auto_conexion.ip

string

IP address used in the connection attempt.

auto_conexion.mensaje

string

Human-readable status message.

auto_conexion.verificado

boolean

Whether the connection was verified in MikroTik’s active session table.

auto_conexion.session_id

string

MikroTik session ID. Only present when verificado is true.

advertencia

string

Only present when estado_pago is "pending". Contains a human-readable warning message explaining that the payment is awaiting confirmation.

Examples

cURL

curl -X POST "https://api.example.com/api/v1/payments/pagar-mercado-pago" \
  -H "X-API-Key: jwt_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb3V0ZXJfaWQiOjMsImVtcHJlc2FfaWQiOjF9.SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "producto_id": 1,
    "token": "ff8080814c11e237014c1ff593b57b45",
    "payment_method_id": "visa",
    "issuer_id": "310",
    "monto": 15.00,
    "cuotas": 1,
    "nombre_cliente": "María González",
    "email_cliente": "[email protected]",
    "telefono_cliente": "+52 55 9876 5432",
    "device_id": "9b2d5b4678de4d8a86cfab58bc2495df",
    "tipo_usuario": "usuario_contrasena",
    "mac_cliente": "CC:DD:EE:FF:00:11",
    "ip_cliente": "192.168.88.200",
    "conexion_automatica": true
  }'

Success Response `200 OK`

{
  "success": true,
  "id_transaccion": "87654321",
  "estado_pago": "approved",
  "tipo_usuario": "usuario_contrasena",
  "usuario_hotspot": {
    "usuario": "XK7P2Q",
    "contrasena": "9351"
  },
  "producto": {
    "nombre": "1 Hora de Internet",
    "precio": 15.0,
    "moneda": "MXN",
    "perfil_mikrotik": "5Mbps-1hora"
  },
  "cliente": {
    "nombre": "María González",
    "email": "[email protected]"
  },
  "mercado_pago": {
    "payment_id": 87654321,
    "status": "approved",
    "status_detail": "accredited",
    "installments": 1,
    "payment_method": {
      "id": "visa",
      "type": "credit_card",
      "issuer_id": "310"
    },
    "raw_response": {}
  },
  "timestamp": "2024-07-01T16:45:00.987654",
  "auto_conexion": {
    "estado": "conectado",
    "mac": "CC:DD:EE:FF:00:11",
    "ip": "192.168.88.200",
    "mensaje": "¡Conexión establecida con éxito! Disfrute de Internet sin límites",
    "verificado": true,
    "session_id": "hs-session-0042"
  }
}

GET /api/v1/payments/estado-pago/

Check the current status of a Mercado Pago payment. Useful for polling pending payments or verifying a completed transaction.

Headers

X-API-Key

string

required

Router API Key. The company associated with the key must have Mercado Pago configured.

Path Parameters

payment_id

integer

required

The numeric Mercado Pago payment ID returned in mercado_pago.payment_id from the payment response.

Response

{
  "success": true,
  "payment_id": 87654321,
  "status": "approved",
  "status_detail": "accredited",
  "amount": 15.0,
  "currency_id": "MXN",
  "date_approved": "2024-07-01T16:45:01.000Z",
  "date_last_updated": "2024-07-01T16:45:01.000Z"
}

Error Codes

Status	Trigger
`400 Bad Request`	Mercado Pago not configured for this company, or `transaction_amount` does not match the product price (±0.01 tolerance).
`402 Payment Required`	Payment was rejected by Mercado Pago (e.g., insufficient funds, declined by issuer). MikroTik user is rolled back.
`404 Not Found`	`producto_id` does not exist or does not belong to the authenticated company.
`500 Internal Server Error`	Failed to create MikroTik user, unexpected error from Mercado Pago, or internal server fault.

When the company has Telegram notifications enabled (notificaciones_telegram = true), this endpoint sends a background notification to the configured telegram_chat_id on both successful payments and rejected ones (HTTP 402). These notifications are sent asynchronously and do not affect the API response time.

Public Endpoints

Admin Endpoints

Super Admin Endpoints

Webhooks

POST /api/v1/payments/pagar-mercado-pago — MercadoPago

Endpoints