> ## 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.

# Iniciar jornada Pix com biometria

> Cria uma transação e devolve a URL da jornada biométrica.

## Comportamento observado

* `urls_callback` é um objeto. Se o objeto for enviado, envie as URLs `success` e `failure`.
* A configuração do processador ainda pode exigir nome, email, telefone, documento e endereço.
* Envie sempre `document_number`: a execução da jornada e a criação da transação podem lê-lo mesmo quando a validação condicional não o exige.
* Quando `is_biometrics_pix` não é enviado, o Gateway define o valor como `true`.
* Quando `pix_message` não é enviado, o Gateway usa `Jornada Pix com Biometria para: {alias do processador}`.
* Os limites mínimo e máximo do processador também são aplicados ao valor.
* A validade da URL e o comportamento do widget dependem do processador ativo.
* A jornada biométrica exige um processador que ofereça essa operação. A implementação atual da LBPay não é elegível. Se a seleção escolher LBPay, o Gateway devolve o erro genérico HTTP 500.

> [!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/journey
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/journey:
    post:
      tags:
        - Pix
      summary: Iniciar jornada Pix com biometria
      description: Cria uma transação e devolve a URL da jornada biométrica.
      operationId: reference_pix_biometric-journey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              properties:
                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
                merchant_transaction_id:
                  type: string
                  description: Identificador da transação no estabelecimento.
                  maxLength: 255
                first_name:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Nome. Pode se tornar obrigatório conforme a configuração do
                    processador.
                  maxLength: 255
                last_name:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Sobrenome. Pode se tornar obrigatório conforme a
                    configuração do processador.
                  maxLength: 255
                email:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Email. Pode se tornar obrigatório conforme a configuração do
                    processador.
                  format: email
                  maxLength: 255
                document_number:
                  type:
                    - string
                    - 'null'
                  description: >-
                    CPF ou CNPJ. A obrigatoriedade depende da configuração do
                    processador.
                mobile_phone:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Telefone. O validador usa o nome mobile_phone e pode
                    torná-lo obrigatório conforme o processador.
                  maxLength: 15
                phone_number:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Telefone lido pelo processador e persistido na transação.
                    Quando o telefone for exigido, envie também mobile_phone com
                    o mesmo valor.
                  maxLength: 15
                ip_address:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Endereço IP do pagador. O valor segue para o processador e
                    para o evento da transação.
                bank_accounts_allowed:
                  type:
                    - array
                    - 'null'
                  description: >-
                    Contas bancárias permitidas para o pagamento. O controller
                    não valida o formato; os campos aceitos e seu efeito
                    dependem do processador ativo.
                  items:
                    type: object
                    additionalProperties: true
                    properties:
                      ispb:
                        type: string
                        description: ISPB da instituição.
                      account_number:
                        type: string
                        description: Número da conta.
                      branch:
                        type: string
                        description: Agência da conta.
                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
                dynamic_descriptor:
                  type:
                    - string
                    - 'null'
                  description: Descrição dinâmica opcional, com até 38 caracteres.
                  maxLength: 38
                street_address_1:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Primeira linha do endereço. Pode ser obrigatória conforme o
                    processador.
                  maxLength: 255
                street_address_2:
                  type:
                    - string
                    - 'null'
                  description: Segunda linha do endereço.
                  maxLength: 255
                city:
                  type:
                    - string
                    - 'null'
                  description: Cidade. Pode ser obrigatória conforme o processador.
                  maxLength: 255
                state:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Estado alfanumérico. Pode ser obrigatório conforme o
                    processador.
                  maxLength: 3
                country:
                  type:
                    - string
                    - 'null'
                  description: >-
                    País em código alfanumérico de dois caracteres. Pode ser
                    obrigatório conforme o processador.
                  minLength: 2
                  maxLength: 2
                zip:
                  type:
                    - string
                    - 'null'
                  description: CEP, com pelo menos dois caracteres.
                  minLength: 2
                shipping_street_address_1:
                  type:
                    - string
                    - 'null'
                  description: Primeira linha do endereço de entrega.
                  maxLength: 255
                shipping_street_address_2:
                  type:
                    - string
                    - 'null'
                  description: Segunda linha do endereço de entrega.
                  maxLength: 255
                shipping_city:
                  type:
                    - string
                    - 'null'
                  description: Cidade de entrega.
                  maxLength: 255
                shipping_state:
                  type:
                    - string
                    - 'null'
                  description: Estado de entrega alfanumérico.
                  maxLength: 3
                shipping_country:
                  type:
                    - string
                    - 'null'
                  description: País de entrega em código alfanumérico de dois caracteres.
                  minLength: 2
                  maxLength: 2
                shipping_zip:
                  type:
                    - string
                    - 'null'
                  description: CEP de entrega, com pelo menos dois caracteres.
                  minLength: 2
                return_url:
                  type:
                    - string
                    - 'null'
                  description: >-
                    URL de retorno, obrigatória quando o processador selecionado
                    é do tipo wallet.
                  format: uri
                meta:
                  description: Metadados opcionais persistidos com a transação.
                pix_message:
                  type:
                    - string
                    - 'null'
                  description: Mensagem Pix. Máximo de 140 caracteres.
                  maxLength: 140
                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
                birth_date:
                  type:
                    - string
                    - 'null'
                  description: Data de nascimento.
                  format: date
                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
                widget_description:
                  type: string
                  description: Texto exibido no widget.
                  maxLength: 255
                payer_bank_description:
                  type: string
                  description: Texto exibido no extrato do pagador.
                  maxLength: 255
                urls_callback:
                  type: object
                  additionalProperties: false
                  properties:
                    success:
                      type: string
                      description: URL de redirecionamento após sucesso.
                      format: uri
                    failure:
                      type: string
                      description: URL de redirecionamento após falha.
                      format: uri
                  required:
                    - success
                    - failure
                is_biometrics_pix:
                  type: boolean
                  default: true
                  description: >-
                    Indica a jornada biométrica. Se omitido, o Gateway define
                    true; false enviado explicitamente é preservado.
              required:
                - amount
                - merchant_transaction_id
                - document_number
                - widget_description
                - payer_bank_description
            example:
              amount: 25
              merchant_transaction_id: 50000000-0000-4000-8000-000000000006
              first_name: Cliente
              last_name: Exemplo
              email: cliente@example.com
              document_number: '12345678909'
              widget_description: Pagamento de exemplo
              payer_bank_description: AZENTECH DEMO
              is_biometrics_pix: false
              urls_callback:
                success: https://merchant.example/success
                failure: https://merchant.example/failure
      responses:
        '200':
          description: Jornada criada.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction:
                    $ref: '#/components/schemas/Transaction'
                  url:
                    type: string
                    description: URL da jornada.
                    format: uri
                required:
                  - transaction
                  - url
              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-000000000006
                  transaction_type: pix
                  first_name: Cliente
                  last_name: Exemplo
                  email: cliente@example.com
                  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: success
                      event_type: auth
                      amount: '25.00'
                      ip_address: null
                      processor_code: null
                      processor_message: null
                      processor_transaction_id: sandbox-event-1001
                      batch_id: null
                      qrcode: >-
                        00020101021226850014br.gov.bcb.pix2563example.invalid/pix/1001
                      qrcode_image: ''
                      pix_key_type: null
                      pix_key_value: null
                      pix_message: 'Jornada Pix com Biometria 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: cashin
                  error: null
                  e2e_id: null
                  source: player
                  tag: null
                url: https://journey.example/10000000-0000-4000-8000-000000000001
        '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 entrada está bloqueado para o estabelecimento.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                error:
                  message:
                    base:
                      - Flow type cash_in 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:
    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
    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
    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.