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

# Criar pagamento Pix por conta

> Cria um pagamento Pix para dados bancários informados no corpo.

## Comportamento observado

* O Gateway define `pix_type` como `Manual`. Não envie esse campo.
* `first_name` e `last_name` não são exigidos por esta validação. `email` é opcional.
* O validador torna `document_number` condicional, mas o fluxo de pagamento o lê sem fallback. Envie sempre um CPF ou CNPJ válido.
* Se `pix_message` não for enviado, o Gateway usa `Pagamento para: {alias do processador}`.
* Os limites mínimo e máximo do processador também são aplicados ao valor.
* Para LBPay, repetir o mesmo `merchant_transaction_id` com a mesma intenção e o mesmo processador devolve a transação existente com HTTP 200 sem criar outra transferência no provedor. Se a intenção mudar, o Gateway devolve HTTP 409.
* Nesse replay da LBPay, a rota volta a chamar o envio legado do webhook `payment`. Se a transação tiver origem `player` e houver uma inscrição, pode ocorrer um novo envio.
* O código-fonte da rota contém um espaço final, mas o roteador registra e resolve `/api/pix/manual_pay`.

> [!NOTE]
>
> Os exemplos usam identificadores e credenciais sintéticos. Os resultados do processador dependem do credenciamento e da configuração do estabelecimento.


## OpenAPI

````yaml openapi.json POST /api/pix/manual_pay
openapi: 3.1.0
info:
  title: Azentech Payments API
  version: 1.0.0
  description: >-
    Contrato HTTP público das operações de pagamento, consulta, sandbox e
    webhooks da Azentech. A especificação contém apenas o ambiente de
    homologação confirmado.
servers:
  - url: https://gateway.staging.azentech.dev
    description: Homologação (staging)
security: []
tags:
  - name: Pix
    description: Cobranças, pagamentos, aportes, retiradas e jornada biométrica.
  - name: Transações
    description: Consulta e reembolso de transações.
  - name: Saldos
    description: Saldos atuais, históricos e resumo financeiro.
  - name: Relatórios
    description: Extrato e posição financeira.
  - name: Sandbox
    description: Simulações disponíveis para processadores elegíveis em modo de teste.
paths:
  /api/pix/manual_pay:
    post:
      tags:
        - Pix
      summary: Criar pagamento Pix por conta
      description: Cria um pagamento Pix para dados bancários informados no corpo.
      operationId: reference_pix_manual-payment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              properties:
                merchant_transaction_id:
                  type: string
                  description: Identificador da transação no estabelecimento.
                  maxLength: 255
                amount:
                  type: number
                  description: >-
                    Valor em reais, com no máximo duas casas decimais. Deve ser
                    maior que zero e menor que 99.999.999 antes da aplicação dos
                    limites do processador.
                  exclusiveMinimum: 0
                  exclusiveMaximum: 99999999
                  multipleOf: 0.01
                pix_message:
                  type:
                    - string
                    - 'null'
                  description: Mensagem Pix. Máximo de 140 caracteres.
                  maxLength: 140
                first_name:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Nome opcional repassado ao pagamento manual Celcoin; a
                    aceitação de valor vazio pelo processador não foi
                    confirmada.
                  maxLength: 255
                last_name:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Sobrenome opcional repassado ao pagamento manual Celcoin; a
                    aceitação de valor vazio pelo processador não foi
                    confirmada.
                  maxLength: 255
                document_number:
                  type:
                    - string
                    - 'null'
                  description: >-
                    CPF ou CNPJ. A obrigatoriedade depende da configuração do
                    processador.
                email:
                  type:
                    - string
                    - 'null'
                  description: Email opcional.
                  format: email
                  maxLength: 255
                branch_code:
                  type: string
                  description: Agência bancária.
                  maxLength: 255
                account_number:
                  type: string
                  description: Número da conta.
                  maxLength: 255
                ispb:
                  type: string
                  description: ISPB da instituição.
                  maxLength: 255
                account_type:
                  type: string
                  description: Tipo da conta.
                  enum:
                    - CACC
                    - SVGS
                    - SLRY
                    - TRAN
                processor_id:
                  type:
                    - string
                    - 'null'
                  description: >-
                    UUID do processador. Na seleção comum, o Gateway usa o
                    primeiro Pix habilitado por precedência; este campo só
                    restringe a seleção quando source é settlement.
                  format: uuid
                source:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Origem da transação. Quando omitida em uma cobrança, o
                    Gateway assume player.
                  enum:
                    - player
                    - settlement
                    - vendor
                    - funding
                    - internal
                    - balancing
                    - null
                tag:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Tag da transação. Conforme a configuração do
                    estabelecimento, pode ser obrigatória, livre ou restrita a
                    CPF ou CNPJ. Tags que contêm internal suprimem os webhooks
                    de pagamento.
                  maxLength: 50
              required:
                - merchant_transaction_id
                - amount
                - document_number
                - branch_code
                - account_number
                - ispb
                - account_type
            example:
              merchant_transaction_id: 50000000-0000-4000-8000-000000000004
              amount: 75.25
              document_number: '12345678909'
              branch_code: '0001'
              account_number: 123456-7
              ispb: '12345678'
              account_type: CACC
      responses:
        '200':
          description: Transação criada ou atualizada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionEnvelope'
              example:
                transaction:
                  id: 10000000-0000-4000-8000-000000000001
                  merchant_id: 20000000-0000-4000-8000-000000000001
                  user_id: 30000000-0000-4000-8000-000000000001
                  processor_id: 40000000-0000-4000-8000-000000000001
                  merchant_transaction_id: 50000000-0000-4000-8000-000000000004
                  transaction_type: pix
                  first_name: null
                  last_name: null
                  email: null
                  updated_at: '2026-10-23T14:30:00+00:00'
                  created_at: '2026-10-23T14:30:00+00:00'
                  events:
                    - id: 60000000-0000-4000-8000-000000000001
                      success: true
                      status: pending_settlement
                      event_type: payment
                      amount: '75.25'
                      ip_address: null
                      processor_code: null
                      processor_message: null
                      processor_transaction_id: sandbox-event-1001
                      batch_id: null
                      qrcode: null
                      qrcode_image: ''
                      pix_key_type: null
                      pix_key_value: null
                      pix_message: 'Pagamento para: CONTA DEMO'
                      updated_at: '2026-10-23T14:30:00+00:00'
                      created_at: '2026-10-23T14:30:00+00:00'
                  document_number: '12345678909'
                  status: pending
                  flow_type: cashout
                  error: null
                  e2e_id: null
                  source: player
                  tag: null
        '401':
          description: Token ausente, inválido ou sem acesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                error:
                  message:
                    base:
                      - Not authenticated
                  status: 401
        '403':
          description: O fluxo de saída está bloqueado para o estabelecimento.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                error:
                  message:
                    base:
                      - Flow type cash_out has blocked
                  status: 403
        '409':
          description: Uma transação duplicada foi bloqueada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                error:
                  message:
                    base:
                      - Transaction can not be processed due duplicates entry.
                  status: 409
        '422':
          description: Dados inválidos ou operação indisponível para a configuração atual.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/GatewayError'
              examples:
                validation:
                  value:
                    message: The given data was invalid.
                    errors:
                      amount:
                        - The amount field is required.
                capability:
                  value:
                    error:
                      message:
                        base:
                          - Pix processor not found.
                      status: 422
        '500':
          description: Falha interna ou falha não traduzida do processador.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                error:
                  message:
                    fatal: >-
                      Something went wrong. Please refer to support with the
                      following code: 0000000000
                  status: 500
      security:
        - BearerAuth: []
components:
  schemas:
    TransactionEnvelope:
      type: object
      additionalProperties: false
      properties:
        transaction:
          $ref: '#/components/schemas/Transaction'
      required:
        - transaction
    GatewayError:
      type: object
      additionalProperties: false
      properties:
        error:
          type: object
          additionalProperties: false
          properties:
            message:
              oneOf:
                - type: string
                - type: object
                  additionalProperties:
                    oneOf:
                      - type: string
                      - type: array
                        items:
                          type: string
              description: Mensagem simples ou mapa de campos para listas de mensagens.
            status:
              type: integer
              description: Código HTTP devolvido.
          required:
            - message
            - status
      required:
        - error
    ValidationError:
      type: object
      additionalProperties: false
      properties:
        message:
          type: string
          description: Resumo da falha de validação.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - message
        - errors
    Transaction:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: UUID da transação na Azentech.
          format: uuid
        merchant_id:
          type: string
          description: UUID do estabelecimento.
          format: uuid
        user_id:
          type:
            - string
            - 'null'
          description: UUID do usuário associado.
          format: uuid
        processor_id:
          type: string
          description: UUID do processador selecionado.
          format: uuid
        merchant_transaction_id:
          type: string
          description: Identificador informado pelo estabelecimento.
          maxLength: 255
        transaction_type:
          type: string
          description: Tipo da transação.
        first_name:
          type:
            - string
            - 'null'
          description: Nome do pagador ou recebedor.
        last_name:
          type:
            - string
            - 'null'
          description: Sobrenome do pagador ou recebedor.
        email:
          type:
            - string
            - 'null'
          description: Email do pagador ou recebedor.
          format: email
        updated_at:
          type: string
          description: Data e hora da última alteração.
          format: date-time
        created_at:
          type: string
          description: Data e hora de criação.
          format: date-time
        events:
          type: array
          items:
            $ref: '#/components/schemas/TransactionEvent'
        document_number:
          type:
            - string
            - 'null'
          description: CPF ou CNPJ vinculado à transação.
        status:
          type: string
          description: Estado agregado da transação.
          enum:
            - pending
            - success
            - failed
            - expired
            - in_protest
            - canceled
        flow_type:
          type: string
          description: Direção financeira da transação.
          enum:
            - cashin
            - cashout
            - settlement
        error:
          anyOf:
            - $ref: '#/components/schemas/TransactionError'
            - type: 'null'
        e2e_id:
          type:
            - string
            - 'null'
          description: Identificador EndToEnd do Pix.
        source:
          type:
            - string
            - 'null'
          description: Origem interna da transação.
        tag:
          type:
            - string
            - 'null'
          description: Tag associada à transação.
      required:
        - id
        - merchant_id
        - processor_id
        - merchant_transaction_id
        - transaction_type
        - events
        - status
        - flow_type
        - created_at
        - updated_at
    TransactionEvent:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: UUID do evento.
          format: uuid
        success:
          type: boolean
          description: Resultado informado pelo processador.
        status:
          type: string
          description: Estado calculado do evento.
        event_type:
          type: string
          description: Tipo do evento.
        amount:
          oneOf:
            - type: string
            - type: number
          description: Valor do evento em reais.
        ip_address:
          type:
            - string
            - 'null'
          description: IP associado ao evento.
        processor_code:
          type:
            - string
            - 'null'
          description: Código devolvido pelo processador.
        processor_message:
          type:
            - string
            - 'null'
          description: Mensagem devolvida pelo processador.
        processor_transaction_id:
          type:
            - string
            - 'null'
          description: Identificador do evento no processador.
        batch_id:
          type:
            - string
            - 'null'
          description: Identificador do lote, quando houver.
        qrcode:
          type:
            - string
            - 'null'
          description: Payload EMV do QR Code Pix.
        qrcode_image:
          type: string
          description: Imagem do QR Code ou string vazia quando não gerada.
        pix_key_type:
          type:
            - string
            - 'null'
          description: Tipo da chave Pix.
        pix_key_value:
          type:
            - string
            - 'null'
          description: Valor da chave Pix.
        pix_message:
          type:
            - string
            - 'null'
          description: Mensagem Pix.
        updated_at:
          type: string
          description: Data e hora da última alteração.
          format: date-time
        created_at:
          type: string
          description: Data e hora da criação.
          format: date-time
      required:
        - id
        - success
        - status
        - event_type
        - amount
        - qrcode_image
        - updated_at
        - created_at
    TransactionError:
      type: object
      additionalProperties: true
      description: Erro persistido na transação. As chaves dependem do processador.
      properties:
        code:
          type:
            - string
            - 'null'
          description: Código do erro.
        message:
          type:
            - string
            - 'null'
          description: Descrição do erro.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: Token de acesso fornecido para o estabelecimento.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.