openapi: 3.1.0
info:
  title: Neat México API
  summary: API de cobros de Neat México para comercios.
  description: >-
    Endpoints que un comercio integra desde su propio servidor: crear una sesión de checkout,
    consultar su estado y descargar el archivo de conciliación. El checkout en sí lo aloja Neat; esos
    endpoints de pagador no están cubiertos por esta especificación.
  version: 0.1.0
servers:
  - url: https://api-beta.neatpagos.mx/v1
    description: Pruebas
  - url: https://api.neatpagos.mx/v1
    description: Producción
security:
  - bearerAuth: []
tags:
  - name: checkout-sessions
    description: Crear y consultar sesiones de checkout.
  - name: reconciliation
    description: Conciliación de pagos.
paths:
  /checkout-sessions:
    post:
      operationId: createCheckoutSession
      tags: [checkout-sessions]
      summary: Crear una sesión de checkout
      description: >-
        Crea una obligación de cobro identificada por external_reference y una sesión de checkout
        para ella. Documentado en detalle en /cobros/sesiones-de-checkout/.
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: Identifica esta solicitud de creación. 8-128 caracteres ASCII [A-Za-z0-9._:-].
          schema:
            type: string
            minLength: 8
            maxLength: 128
            pattern: '^[A-Za-z0-9._:-]{8,128}$'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCheckoutSessionRequest'
      responses:
        '201':
          description: Sesión creada, o la misma respuesta guardada si se repitió una Idempotency-Key ya usada con el mismo cuerpo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCheckoutSessionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ProviderDisabled'
        '409':
          description: Conflicto de idempotencia o de la obligación.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: >-
            Un campo no cumple su formato, el monto excede tu límite, el return_id no está registrado, la
            categoría no está habilitada para tu comercio (CATEGORY_NOT_ALLOWED), quien paga la comisión no
            está habilitado para tu comercio (FEE_BEARER_NOT_ALLOWED), o la comisión que absorbe tu comercio
            no deja monto a depositar (AMOUNT_BELOW_FEE).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
  /checkout-sessions/{sessionId}:
    get:
      operationId: getCheckoutSession
      tags: [checkout-sessions]
      summary: Consultar una sesión de checkout
      description: Documentado en detalle en /cobros/sesiones-de-checkout/.
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        '200':
          description: Estado de la sesión y su pago más reciente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutSessionView'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ProviderDisabled'
        '404':
          description: La sesión no existe, o pertenece a otro comercio.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
  /reconciliation/payments.csv:
    get:
      operationId: downloadReconciliationCsv
      tags: [reconciliation]
      summary: Descargar el CSV de conciliación
      description: Documentado en detalle en /conciliacion/archivo-csv/.
      responses:
        '200':
          description: Un pago por fila, ordenados por created_at ascendente.
          content:
            text/csv:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ProviderDisabled'
        '429':
          $ref: '#/components/responses/RateLimited'
webhooks:
  paymentEvent:
    post:
      operationId: paymentEvent
      # Neat calls the merchant here; the merchant does not call Neat. Without this the operation
      # inherits the document's bearerAuth and every generated client asks for an API key it has no
      # business holding.
      security: []
      summary: Evento de pago enviado a tu URL de webhook
      description: >-
        Documentado en detalle en /webhooks/eventos-y-firma/. La firma en el encabezado
        Neat-Signature se verifica como en /webhooks/verificar-la-firma/.
      parameters:
        - name: Neat-Event-Id
          in: header
          required: true
          schema:
            type: string
        - name: Neat-Signature
          in: header
          required: true
          description: 'Formato: t=<segundos unix>,v1=<HMAC-SHA256 hexadecimal>.'
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentEvent'
      responses:
        '200':
          description: Cualquier 2xx confirma la entrega. Neat reintenta en cualquier otro caso.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key de tu comercio, entregada durante el alta.
  responses:
    Unauthorized:
      description: Falta el encabezado Authorization, o la API key es inválida.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
    ProviderDisabled:
      description: Tu comercio está deshabilitado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
    RateLimited:
      description: Superaste el límite por minuto de este endpoint.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Segundos a esperar antes de reintentar.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
  schemas:
    ApiErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message, request_id]
          properties:
            code:
              type: string
              description: Código estable. Ver /referencia/errores/.
            message:
              type: string
            field:
              type: string
            request_id:
              type: string
    Payer:
      type: object
      additionalProperties: false
      # The API rejects an empty payer: at least one of the two has to be there.
      minProperties: 1
      properties:
        email:
          type: string
          format: email
          maxLength: 254
        name:
          type: string
          minLength: 1
          maxLength: 100
    PaymentCategory:
      type: string
      enum: [maintenance_fee, rent, rent_guarantee_insurance]
      description: >-
        Qué está pagando el pagador: cuota de mantenimiento, renta o póliza de renta. Con ella cambian el
        texto del checkout y de los correos al pagador.
    FeeBearer:
      type: string
      enum: [payer, provider]
      description: >-
        Quién paga la comisión de Neat. payer: el pagador la paga sumada al monto y se deposita el monto
        completo. provider: tu comercio la absorbe, el pagador paga exactamente el monto y la
        comisión con su IVA se descuenta del depósito. Ver /cobros/importes-y-comisiones/.
    CreateCheckoutSessionRequest:
      type: object
      required: [external_reference, concept, amount_minor, currency, return_id, unit_id]
      additionalProperties: false
      properties:
        external_reference:
          type: string
          pattern: '^[A-Za-z0-9._-]{1,100}$'
          description: Identifica tu obligación de cobro. Único por comercio.
        category:
          $ref: '#/components/schemas/PaymentCategory'
          description: >-
            Opcional si tu comercio tiene habilitada una sola categoría, que es la que se usa; obligatoria
            si tiene varias. Una categoría no habilitada responde 422 CATEGORY_NOT_ALLOWED. Término
            inmutable de la obligación, como el monto.
        concept:
          type: string
          minLength: 1
          maxLength: 140
          description: Se muestra al pagador.
        amount_minor:
          type: integer
          minimum: 1
          description: >-
            Entero en centavos: MXN 12,850.00 se envía como 1285000, y 12850 son MXN 128.50. Este
            esquema sólo exige 1; el mínimo real es 2000 (MXN 20.00) salvo que tu comercio tenga otro, y
            el máximo es el límite acordado con tu comercio. Fuera de ese rango la API responde 422
            VALIDATION_ERROR con field=amount_minor, y el mensaje dice el límite en centavos y en pesos.
        currency:
          type: string
          enum: [MXN]
        return_id:
          type: string
          pattern: '^[A-Za-z0-9_-]{1,50}$'
          description: Debe estar registrado y activo. Ver /empezar/alta-de-tu-comercio/.
        unit_id:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            Tu identificador de la unidad (departamento, lote) que se cobra, único dentro del
            beneficiario: "301", "Torre B PG-1". Letras, números, espacios y . _ # / -; empieza con letra
            o número y no termina en espacio. Se compara exacto ("301" y "Depto 301" son dos unidades),
            así que manda siempre el mismo valor para la misma unidad. Término inmutable de la
            obligación: reutilizar un external_reference con otro unit_id responde 409
            OBLIGATION_CONFLICT. Ver /cobros/sesiones-de-checkout/#unidad.
        payer:
          $ref: '#/components/schemas/Payer'
        metadata:
          type: object
          description: >-
            Sólo de escritura: no vuelve en ninguna respuesta, webhook ni en el archivo de
            conciliación. Al reutilizar un external_reference se conserva el de la primera sesión.
          propertyNames:
            pattern: '^[A-Za-z0-9_-]{1,40}$'
          additionalProperties:
            type: string
            maxLength: 200
          maxProperties: 10
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'
        fee_bearer:
          $ref: '#/components/schemas/FeeBearer'
          description: >-
            Opcional si tu comercio tiene habilitada una sola forma, que es la que se usa; obligatorio si
            tiene las dos. Una forma no habilitada responde 422 FEE_BEARER_NOT_ALLOWED. Queda fija en la
            sesión: lo que el pagador ve en el checkout es lo que se le cobra.
    Beneficiary:
      type: object
      description: >-
        Solo para comercios que cobran por varios beneficiarios (integradores). Obligatorio para
        ellos y rechazado para el resto. Término inmutable de la obligación. legal_name es el nombre
        que ve el pagador y vuelve como payee_name; reference, rfc y clabe nunca vuelven en ninguna
        respuesta, webhook ni archivo de conciliación.
      required: [reference, legal_name, rfc, clabe]
      additionalProperties: false
      properties:
        reference:
          type: string
          pattern: '^[A-Za-z0-9._-]{1,64}$'
          description: Tu identificador del beneficiario (por ejemplo, del condominio).
        legal_name:
          type: string
          minLength: 1
          maxLength: 120
          description: Razón social del titular de la cuenta. Es el nombre que ve el pagador.
        rfc:
          type: string
          description: RFC del titular, 12 caracteres (persona moral) o 13 (persona física).
        clabe:
          type: string
          pattern: '^[0-9]{18}$'
          description: >-
            CLABE de 18 dígitos, como texto y con sus ceros iniciales, con dígito verificador
            válido.
    CreateCheckoutSessionResponse:
      type: object
      required: [session_id, checkout_url, expires_at, status, fee_bearer]
      properties:
        session_id:
          type: string
        checkout_url:
          type: string
          format: uri
          description: Termina en /pagar/<token>. Redirige al pagador aquí.
        expires_at:
          type: string
          format: date-time
          description: 30 minutos después de creada.
        status:
          type: string
          enum: [open]
        fee_bearer:
          $ref: '#/components/schemas/FeeBearer'
    PaymentView:
      type: object
      required:
        - payment_id
        - version
        - status
        - currency
        - principal_amount_minor
        - payer_fee_minor
        - payer_fee_tax_minor
        - provider_fee_minor
        - provider_fee_tax_minor
        - charged_amount_minor
        - provider_net_amount_minor
        - refunded_amount_minor
        - fee_bearer
        - paid_at
        - cancellation_state
        - category
        - concept
        - payee_name
      properties:
        payment_id:
          type: string
        version:
          type: integer
        status:
          type: string
          enum: [pending, succeeded, failed, partially_refunded, refunded]
        currency:
          type: string
          enum: [MXN]
        principal_amount_minor:
          type: integer
        payer_fee_minor:
          type: integer
        payer_fee_tax_minor:
          type: integer
        provider_fee_minor:
          type: integer
        provider_fee_tax_minor:
          type: integer
        charged_amount_minor:
          type: [integer, 'null']
        provider_net_amount_minor:
          type: [integer, 'null']
        refunded_amount_minor:
          type: integer
        fee_bearer:
          $ref: '#/components/schemas/FeeBearer'
          description: Fijo desde que se reservó el pago, igual que los montos de comisión.
        paid_at:
          type: [string, 'null']
          format: date-time
        cancellation_state:
          type: string
          enum: [none, requested, completed, rejected]
        category:
          oneOf:
            - $ref: '#/components/schemas/PaymentCategory'
            - type: 'null'
          description: >-
            Null si el pago no tiene obligación (una transferencia SPEI que no encontró una obligación
            abierta por su monto) o si la obligación del pago ya no se puede leer.
        concept:
          type: [string, 'null']
        payee_name:
          type: [string, 'null']
    CheckoutSessionView:
      type: object
      required:
        [
          session_id,
          status,
          external_reference,
          category,
          concept,
          amount_minor,
          currency,
          fee_bearer,
          expires_at,
          payment,
        ]
      properties:
        session_id:
          type: string
        status:
          type: string
          enum: [open, processing, completed, canceled, expired]
          description: Ver la nota sobre "expired" en /cobros/estados-y-glosario/.
        external_reference:
          type: string
        category:
          $ref: '#/components/schemas/PaymentCategory'
        concept:
          type: string
        amount_minor:
          type: integer
        currency:
          type: string
          enum: [MXN]
        fee_bearer:
          $ref: '#/components/schemas/FeeBearer'
        expires_at:
          type: string
          format: date-time
        payment:
          oneOf:
            - $ref: '#/components/schemas/PaymentView'
            - type: 'null'
    PaymentEvent:
      type: object
      required: [event_id, type, api_version, provider_id, occurred_at, resource, data]
      properties:
        event_id:
          type: string
        type:
          type: string
          enum: [payment.pending, payment.succeeded, payment.failed, payment.refunded]
        api_version:
          type: string
          enum: ['v1']
        provider_id:
          type: string
        occurred_at:
          type: string
          format: date-time
        resource:
          type: object
          required: [type, id, version, session_id, external_reference]
          properties:
            type:
              type: string
              enum: [payment]
            id:
              type: string
            version:
              type: integer
            session_id:
              type: [string, 'null']
              description: >-
                La sesión de checkout del pago. Es el mismo valor que recibiste al crearla. null para un
                pago que no corresponde a ninguna sesión: una transferencia SPEI que no coincidió con una
                obligación abierta de la misma unidad y el mismo monto.
            external_reference:
              type: [string, 'null']
              description: >-
                Tu propia referencia de la obligación, tal como la mandaste al crear la sesión. null en el
                mismo caso que session_id: el dinero llegó, pero no salda ninguna obligación tuya.
        data:
          $ref: '#/components/schemas/PaymentView'
