POST /api/v1/payments/pagar-conekta — Conekta Payment

The /api/v1/payments/pagar-conekta endpoint is the core transaction flow for Conekta-powered captive portals. It accepts a Conekta.js card token from the browser, creates a MikroTik Hotspot user with the appropriate profile, charges the card, and returns ready-to-use WiFi credentials. The entire process is atomic from the user’s perspective — if the payment is declined or fails, the hotspot user is immediately deleted so no access is granted without a successful charge.

Create-first, charge-second design: The MikroTik hotspot user is created before the Conekta charge is attempted. If the card charge fails for any reason (declined, expired, network error), the hotspot user is automatically deleted (rolled back) before the error is returned to the client. This ensures no free access is ever granted on a failed payment.

Request

Method: POST
Path: /api/v1/payments/pagar-conekta
Content-Type: application/json

Headers

X-API-Key

string

required

Router API Key in the format jwt_<token>. Identifies the company (providing Conekta credentials) and the router (providing MikroTik credentials).

Body

The request body accepts both the canonical field names (Python) and their Spanish aliases. Both are shown below. Either form is accepted.

producto_id

integer

required

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

token_tarjeta

string

required

Card tokenization token generated by Conekta.js (conekta.Token.create). This token is single-use and expires shortly after creation. Also accepted as card_token.

nombre_cliente

string

required

Full name of the cardholder, passed to Conekta for order creation. Also accepted as customer_name.

email_cliente

string

required

Valid email address of the customer. Used for Conekta order creation and stored in the transaction record. Must be a valid email format. Also accepted as customer_email.

telefono_cliente

string

Customer phone number. Optional — passed to Conekta as additional customer info. Also accepted as customer_phone.

tipo_usuario

string

default:"usuario_contrasena"

Controls the type of credentials generated for the MikroTik hotspot user. Also accepted as user_type.

"usuario_contrasena" — (default) Generates a short alphanumeric username (e.g., "AB3C9D") and a separate numeric password (e.g., "1234"). The user logs in with both.
"pin" — Generates a single 6-digit numeric PIN. The username is the PIN itself, and the password field is empty. Suitable for simpler captive portal flows.

Any value other than these two is silently treated as "usuario_contrasena".

mac_cliente

string

MAC address of the client device (e.g., "AA:BB:CC:DD:EE:FF"). Required if conexion_automatica is true. Used to bind the new hotspot user to the device’s MAC and attempt automatic login via MikroTik’s cookie injection mechanism. Also accepted as mac_address.

ip_cliente

string

Current IP address of the client device on the captive portal network. Used during auto-connection to target the correct active session. Also accepted as ip_address.

info_dispositivo

string

Free-form device information string (e.g., user-agent, device model). Stored in transaction metadata for analytics. Also accepted as device_info.

conexion_automatica

boolean

default:"false"

When true, the server will attempt to automatically authenticate the client device on the MikroTik hotspot immediately after a successful payment, using mac_cliente and ip_cliente. The connection result is reported in the auto_conexion field of the response. Also accepted as auto_connect.If mac_cliente is not provided, this flag is ignored.

Response

On success the endpoint returns HTTP 200 with the following JSON body.

success

boolean

Always true on a successful response.

id_transaccion

string

Conekta Order ID (e.g., "ord_2tV7dXbYzS3kLmNp"). Store this for support and reconciliation purposes.

estado_pago

string

Payment status. Always "paid" in a success response. Any other status is treated as an error and results in a 402 response.

tipo_usuario

string

The user type that was actually used to create the hotspot credentials. Either "usuario_contrasena" or "pin".

usuario_hotspot

object

The WiFi credentials to display to the user.

Show usuario_hotspot fields

usuario_hotspot.usuario

string

The hotspot username. For usuario_contrasena type, this is a short alphanumeric string (e.g., "AB3C9D"). For pin type, this is the 6-digit PIN (e.g., "482917").

usuario_hotspot.contrasena

string

The hotspot password. For usuario_contrasena type, this is a short numeric string. For pin type, this is an empty string "".

producto

object

Summary of the product that was purchased.

Show producto fields

producto.nombre

string

Commercial name of the purchased product.

producto.precio

float

Price charged for the product.

producto.moneda

string

ISO 4217 currency code of the charged amount (e.g., "MXN").

producto.perfil_mikrotik

string

Name of the MikroTik Hotspot profile applied to the new user.

cliente

object

Customer information as submitted in the request.

Show cliente fields

cliente.nombre

string

Customer name as provided in nombre_cliente.

cliente.email

string

Customer email as provided in email_cliente.

timestamp

string

ISO 8601 UTC datetime of when the transaction was completed (e.g., "2024-07-01T15:30:45.123456").

auto_conexion

object

Result of the automatic connection attempt. Present in all responses regardless of whether conexion_automatica was requested.

Show auto_conexion fields

auto_conexion.estado

string

Connection outcome. Either "conectado" (device was successfully authenticated) or "no_conectado" (auto-connection was not attempted or failed).

auto_conexion.mac

string

The MAC address used for the connection attempt. Empty string if not provided.

auto_conexion.ip

string

The IP address used for the connection attempt. Empty string if not provided.

auto_conexion.mensaje

string

Human-readable message describing the connection result. Show this to the user if estado is "no_conectado".

auto_conexion.verificado

boolean

true if the connection was confirmed by checking MikroTik’s active sessions. false if the login was attempted but not verified, or if no connection was attempted.

auto_conexion.session_id

string

MikroTik session identifier. Only present when estado is "conectado" and verificado is true.

Payment Flow

Validate product belongs to the authenticated company
Normalize user_type → "usuario_contrasena" or "pin"
Generate hotspot credentials (username + password or PIN)
── CRITICAL ──  Create MikroTik hotspot user (with assigned profile)
── CRITICAL ──  Charge card via Conekta API
Double-check payment_status == "paid"
   └── If NOT paid → rollback MikroTik user → return 402
Save transaction to database
If auto_connect + mac_address → attempt MikroTik cookie injection
Return credentials + auto_conexion result

Examples

cURL

curl -X POST "https://api.example.com/api/v1/payments/pagar-conekta" \
  -H "X-API-Key: jwt_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb3V0ZXJfaWQiOjMsImVtcHJlc2FfaWQiOjF9.SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "producto_id": 1,
    "token_tarjeta": "tok_test_vzMOe29nPsTenantKc5",
    "nombre_cliente": "Juan Pérez",
    "email_cliente": "[email protected]",
    "telefono_cliente": "+52 55 1234 5678",
    "tipo_usuario": "usuario_contrasena",
    "mac_cliente": "AA:BB:CC:DD:EE:FF",
    "ip_cliente": "192.168.88.150",
    "conexion_automatica": true
  }'

Success Response `200 OK`

{
  "success": true,
  "id_transaccion": "ord_2tV7dXbYzS3kLmNp",
  "estado_pago": "paid",
  "tipo_usuario": "usuario_contrasena",
  "usuario_hotspot": {
    "usuario": "AB3C9D",
    "contrasena": "4821"
  },
  "producto": {
    "nombre": "1 Hora de Internet",
    "precio": 15.0,
    "moneda": "MXN",
    "perfil_mikrotik": "5Mbps-1hora"
  },
  "cliente": {
    "nombre": "Juan Pérez",
    "email": "[email protected]"
  },
  "timestamp": "2024-07-01T15:30:45.123456",
  "auto_conexion": {
    "estado": "conectado",
    "mac": "AA:BB:CC:DD:EE:FF",
    "ip": "192.168.88.150",
    "mensaje": "¡Conexión establecida con éxito! Disfrute de Internet sin límites",
    "verificado": true,
    "session_id": "hs-session-0001"
  }
}

Error Response `402 Payment Required` (card declined)

{
  "detail": "El pago fue declinado. Contacte a su banco."
}

Error Response `404 Not Found` (invalid product)

{
  "detail": "Producto no encontrado"
}

Error Codes

Status	Trigger
`402 Payment Required`	Card declined, payment expired, cancelled, pre-authorized, or any non-`paid` status returned by Conekta.
`404 Not Found`	`producto_id` does not exist or does not belong to the authenticated company.
`500 Internal Server Error`	Failed to create the MikroTik hotspot user, unexpected Conekta error, or internal server fault.

For PIN-type users the usuario_hotspot.contrasena field will be an empty string. Show only the usuario (PIN) to the customer and instruct them to enter it as the username on the captive portal login page.

Public Endpoints

Admin Endpoints

Super Admin Endpoints

Webhooks

POST /api/v1/payments/pagar-conekta — Conekta Payment

Request

Headers

Body

Response

Payment Flow

Examples

cURL

Success Response `200 OK`

Error Response `402 Payment Required` (card declined)

Error Response `404 Not Found` (invalid product)

Error Codes

Build docs developers (and LLMs) love

Public Endpoints

Admin Endpoints

Super Admin Endpoints

Webhooks

Documentation Index

​Request

​Headers

​Body

​Response

​Payment Flow

​Examples

​cURL

​Success Response 200 OK

​Error Response 402 Payment Required (card declined)

​Error Response 404 Not Found (invalid product)

​Error Codes

Build docs developers (and LLMs) love

Request

Headers

Body

Response

Payment Flow

Examples

cURL

Success Response `200 OK`

Error Response `402 Payment Required` (card declined)

Error Response `404 Not Found` (invalid product)

Error Codes