Ir al contenido

Referencia de API

Referencia compacta de los tres endpoints de comercio de la API de Neat México v1. Para el flujo completo con contexto, ve a Sesiones de checkout, Redirección y regreso y Archivo CSV.

Todos los endpoints:

  • Requieren Authorization: Bearer <tu API key>.
  • Devuelven Cache-Control: no-store.
  • Devuelven errores con la forma { "error": { "code", "message", "field"?, "request_id" } }, ver Errores.
Método y ruta Límite Descripción
POST /v1/checkout-sessions 120/min Crea una sesión de checkout.
GET /v1/checkout-sessions/{sessionId} 300/min Consulta el estado de una sesión y su pago más reciente.
GET /v1/reconciliation/payments.csv 10/min Descarga el CSV con todos los pagos de tu comercio.

Crea una obligación de cobro y una sesión de checkout para ella.

Cabeceras: Authorization (obligatoria), Idempotency-Key (obligatoria, 8–128 caracteres [A-Za-z0-9._:-], una nueva por cada intento de cobro), Content-Type: application/json.

Cuerpo:

Campo Tipo Obligatorio
external_reference string, 1–100 ASCII [A-Za-z0-9._-] Sí
concept string, 1–140 caracteres Sí
amount_minor integer positivo, centavos Sí
currency "MXN" Sí
return_id string, 1–50 ASCII [A-Za-z0-9_-] Sí
unit_id string, 1–64: letras, números, espacios, ._#/- Sí
payer.email string, correo, ≤254 No
payer.name string, 1–100 No
metadata objeto, hasta 10 pares string:string No
beneficiary objeto reference, legal_name, rfc, clabe (string de 18 dígitos) Según tu comercio
fee_bearer "payer" o "provider" Según tu comercio

payer.email decide quién puede pagar: si lo mandas, sólo esa dirección recibe el código y puede pagar la sesión. Reutilizar un external_reference con otro monto, moneda, concepto, beneficiario o unit_id responde 409 OBLIGATION_CONFLICT aunque no se haya pagado. Ver Sesiones de checkout.

Ventana de terminal
IDEMPOTENCY_KEY="checkout-$(uuidgen)"
curl -X POST "$NEAT_API_BASE/checkout-sessions" \
-H "Authorization: Bearer $NEAT_API_KEY" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{
"external_reference": "CUOTA-2026-09-000123",
"concept": "Mensualidad de mantenimiento, septiembre 2026",
"amount_minor": 125000,
"currency": "MXN",
"return_id": "principal",
"unit_id": "301"
}'

Respuesta 201 Created:

{
"session_id": "cs_164596add1a3",
"checkout_url": "https://pago.neat.example/pagar/cs_164596add1a3.CQGg0fEWT5o…",
"expires_at": "2026-09-14T23:45:55.013Z",
"status": "open",
"fee_bearer": "payer"
}

Detalle completo de campos, reglas de external_reference, beneficiary y errores en Sesiones de checkout.


Consulta una sesión y su pago más reciente.

Ventana de terminal
curl "$NEAT_API_BASE/checkout-sessions/cs_164596add1a3" \
-H "Authorization: Bearer $NEAT_API_KEY"

Respuesta 200 OK:

{
"session_id": "cs_164596add1a3",
"status": "completed",
"external_reference": "CUOTA-2026-09-000123",
"category": "maintenance_fee",
"concept": "Mensualidad de mantenimiento, septiembre 2026",
"amount_minor": 125000,
"currency": "MXN",
"fee_bearer": "payer",
"expires_at": "2026-09-14T23:45:55.013Z",
"payment": {
"payment_id": "pay_3ac4efd9f068",
"version": 2,
"status": "succeeded",
"currency": "MXN",
"principal_amount_minor": 125000,
"payer_fee_minor": 3750,
"payer_fee_tax_minor": 600,
"provider_fee_minor": 0,
"provider_fee_tax_minor": 0,
"charged_amount_minor": 129350,
"provider_net_amount_minor": 125000,
"refunded_amount_minor": 0,
"fee_bearer": "payer",
"cancellation_state": "none",
"paid_at": "2026-09-14T23:17:17.894Z",
"category": "maintenance_fee",
"concept": "Mensualidad de mantenimiento, septiembre 2026",
"payee_name": "Administradora Ejemplo, S.A. de C.V."
}
}

payment es null antes del primer intento. Ver el significado de cada campo en Importes y comisiones y cada estado en Estados y glosario.


Descarga el CSV con todos los pagos de tu comercio, sin filtro de fecha.

Ventana de terminal
curl "$NEAT_API_BASE/reconciliation/payments.csv" \
-H "Authorization: Bearer $NEAT_API_KEY" \
-o payments.csv

Respuesta 200 OK: Content-Type: text/csv; charset=utf-8. Columnas y ejemplo completo en Archivo CSV.


La forma exacta de cada request y respuesta también está disponible como OpenAPI 3.1, ver OpenAPI.