> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.ntxpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar cobrança SPEI (cash-in)

> **Requer Bearer JWT**. Gera uma CLABE descartável de destino que o pagador deve usar em uma transferência SPEI. Confirmação assíncrona via webhook `cash_in`.



## OpenAPI

````yaml post /api/spei/cash-in
openapi: 3.0.0
info:
  title: NTX Pay Public API — México
  description: >-
    API Pública NTX Pay para integração com SPEI (cash-in/cash-out) no México.
    Todos os valores monetários são expressos em centavos MXN.
  version: 1.0.0
  contact: {}
servers:
  - url: https://sandbox.mx.ntxpay.com
    description: Sandbox
security: []
tags:
  - name: auth
    description: Geração de token via certificado X.509 + clientId/clientSecret
  - name: SPEI
    description: >-
      Transferências interbancárias instantâneas mexicanas (cash-in via CLABE
      descartável; cash-out para CLABE)
  - name: Balance
    description: Consulta de saldo da conta (centavos MXN)
  - name: Webhooks Config
    description: Configuração de webhooks para notificações de eventos
paths:
  /api/spei/cash-in:
    post:
      tags:
        - SPEI
      summary: Criar cobrança SPEI (cash-in)
      description: >-
        **Requer Bearer JWT**. Gera uma CLABE descartável de destino que o
        pagador deve usar em uma transferência SPEI. Confirmação assíncrona via
        webhook `cash_in`.
      operationId: SpeiCashInController_create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpeiCashInInputDto'
      responses:
        '201':
          description: Cobrança SPEI criada (PENDING)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeiCashInOutputDto'
        '400':
          description: Dados inválidos
        '401':
          description: Token inválido
        '502':
          description: Serviço temporariamente indisponível
      security:
        - bearer: []
components:
  schemas:
    SpeiCashInInputDto:
      type: object
      required:
        - amountCentavos
        - customerName
        - customerEmail
      properties:
        amountCentavos:
          type: integer
          minimum: 1000
          description: >-
            Amount in MXN centavos. Minimum 1000 centavos (10.00 MXN) — partner
            bank floor.
          example: 50000
        externalId:
          type: string
          minLength: 1
          maxLength: 100
          description: Identificador externo / referência do cliente.
          example: order-abc-123
        description:
          type: string
          minLength: 1
          maxLength: 255
          example: 'Pedido #123'
        customerName:
          type: string
          minLength: 1
          maxLength: 255
          description: Nome do pagador (mostrado no checkout SPEI)
          example: Juan Perez
        customerEmail:
          type: string
          format: email
          description: Email do pagador
          example: juan@example.com
        customerTaxId:
          type: string
          minLength: 10
          maxLength: 20
          description: RFC/CURP do pagador
          example: PEPJ800101ABC
    SpeiCashInOutputDto:
      type: object
      properties:
        transactionId:
          type: string
          format: uuid
          description: >-
            Identificador publico da transacao (UUID). E o mesmo transactionId
            entregue nos webhooks — use-o para correlacionar e consultar a
            transacao.
          example: 3f2a1c34-9d1e-4c7b-8a5e-2b6f0d9c4e71
        status:
          type: string
          enum:
            - PENDING
            - CONFIRMED
            - FAILED
            - EXPIRED
          example: PENDING
        destinationClabe:
          type: string
          description: CLABE descartável de destino para o pagador transferir
          example: '012180001234567890'
        beneficiary:
          $ref: '#/components/schemas/SpeiCashInBeneficiaryDto'
        referenceNumerical:
          type: string
          nullable: true
          example: '1234567'
        checkoutUrl:
          type: string
          nullable: true
          format: uri
          example: https://pay.ntxpay.com/checkout/xyz
        expiresAt:
          type: string
          nullable: true
          format: date-time
          example: '2026-05-14T23:59:59.000Z'
        amountCentavos:
          type: integer
          example: 50000
    SpeiCashInBeneficiaryDto:
      type: object
      properties:
        name:
          type: string
          example: NTX Pay MX
        taxId:
          type: string
          nullable: true
          example: NTX800101ABC
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT obtido em POST /api/auth/token

````