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

# Reembolsar transação

> Solicita o reembolso total ou parcial de uma cobrança capturada.

## Comportamento observado

* Envie pelo menos um identificador para selecionar a transação pretendida.
* O Gateway atual não rejeita um corpo sem identificadores. Nesse caso, a consulta fica limitada apenas ao estabelecimento e seleciona o primeiro resultado. Não dependa desse comportamento.
* Quando mais de um identificador é enviado, todos precisam corresponder à mesma transação.
* Reembolsos pendentes e falhas sem recuperação durável continuam consumindo o valor capturado disponível.

> [!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/transactions/reimbursement
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/transactions/reimbursement:
    post:
      tags:
        - Transações
      summary: Reembolsar transação
      description: Solicita o reembolso total ou parcial de uma cobrança capturada.
      operationId: reference_transactions_reimburse
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                merchant_transaction_id:
                  type:
                    - string
                    - 'null'
                  description: UUID usado pelo estabelecimento.
                  format: uuid
                e2e_id:
                  type:
                    - string
                    - 'null'
                  description: Identificador EndToEnd.
                transaction_id:
                  type:
                    - string
                    - 'null'
                  description: UUID da transação na Azentech.
                  format: uuid
                amount:
                  type:
                    - number
                    - 'null'
                  minimum: 0.01
                  description: >-
                    Valor em reais. Se omitido, usa o saldo capturado
                    disponível.
            example:
              transaction_id: 10000000-0000-4000-8000-000000000001
              amount: 25.9
      responses:
        '200':
          description: Reembolso processado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    const: Reimbursement processed successfully
                  transaction:
                    $ref: '#/components/schemas/Transaction'
                  reimbursement_event:
                    $ref: '#/components/schemas/ReimbursementEvent'
                required:
                  - message
                  - transaction
                  - reimbursement_event
              example:
                message: Reimbursement processed successfully
                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-000000000001
                  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: '125.90'
                      ip_address: 192.0.2.10
                      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: 'Deposito para: CONTA DEMO'
                      updated_at: '2026-10-23T14:30:00+00:00'
                      created_at: '2026-10-23T14:30:00+00:00'
                    - id: 60000000-0000-4000-8000-000000000003
                      success: true
                      status: success
                      event_type: capture
                      amount: '125.90'
                      ip_address: 192.0.2.10
                      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: 'Deposito para: CONTA DEMO'
                      updated_at: '2026-10-23T14:30:30+00:00'
                      created_at: '2026-10-23T14:30:30+00:00'
                  document_number: '12345678909'
                  status: success
                  flow_type: cashin
                  error: null
                  e2e_id: null
                  source: player
                  tag: demo
                reimbursement_event:
                  id: 60000000-0000-4000-8000-000000000002
                  success: false
                  status: declined
                  event_status: created
                  wallet_recovery_status: null
                  event_type: reimbursement
                  amount: '25.90'
                  processor_transaction_id: sandbox-event-1001
                  updated_at: '2026-10-23T14:31:00+00:00'
                  created_at: '2026-10-23T14:31:00+00:00'
                  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-000000000001
                    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'
                    document_number: '12345678909'
                    status: success
                    flow_type: cashin
                    error: null
                    e2e_id: null
                    source: player
                    tag: demo
                    meta: null
                    transaction_repay_id: null
                    responsable: null
                    observation: null
                    is_repaid: false
                    is_biometrics_pix: false
                  pix_key_type: null
                  pix_key_value: null
                  pix_message: 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
        '404':
          description: Transação ou evento de captura não encontrado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                error:
                  message: Transaction not found.
                  status: 404
        '422':
          description: Dados inválidos ou reembolso rejeitado pelo processador.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/MessageError'
              examples:
                validation:
                  value:
                    message: The given data was invalid.
                    errors:
                      amount:
                        - The amount must be at least 0.01.
                processor:
                  value:
                    message: >-
                      Reimbursement amount exceeds the available captured
                      amount.
        '500':
          description: Falha capturada durante o processamento do reembolso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageError'
              example:
                message: Failed to process reimbursement
      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
    ReimbursementEvent:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: UUID do evento.
          format: uuid
        success:
          type: boolean
        status:
          type: string
          description: Estado calculado do evento.
        event_status:
          type:
            - string
            - 'null'
          description: Estado persistido do evento.
        wallet_recovery_status:
          type:
            - string
            - 'null'
          description: Estado da recuperação da carteira, quando houver.
        event_type:
          type: string
          description: Tipo do evento.
        amount:
          oneOf:
            - type: string
            - type: number
        processor_transaction_id:
          type:
            - string
            - 'null'
          description: Identificador do evento no processador.
        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
        transaction:
          $ref: '#/components/schemas/AppTransaction'
        processor_response_raw:
          type:
            - string
            - 'null'
          description: Somente para usuário administrador.
        processor_response_headers: {}
        processor_response_http_status:
          type:
            - integer
            - 'null'
          description: Somente para usuário administrador.
        processor_response_json: {}
        processor_request_raw:
          type:
            - string
            - 'null'
          description: Somente para usuário administrador.
        error_code:
          type:
            - string
            - 'null'
          description: Somente para usuário administrador.
        error_class:
          type:
            - string
            - 'null'
          description: Somente para usuário administrador.
        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.
      required:
        - id
        - success
        - status
        - event_status
        - wallet_recovery_status
        - event_type
        - amount
        - processor_transaction_id
        - updated_at
        - created_at
        - transaction
        - pix_key_type
        - pix_key_value
        - pix_message
    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
    MessageError:
      type: object
      additionalProperties: true
      properties:
        message:
          type: string
          description: Descrição do erro.
      required:
        - message
    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.
    AppTransaction:
      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
        meta: {}
        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
        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.
        transaction_repay_id:
          type:
            - string
            - 'null'
          description: UUID da transação de repasse, quando existir.
          format: uuid
        responsable:
          type:
            - string
            - 'null'
          description: Responsável registrado, quando existir.
        observation:
          type:
            - string
            - 'null'
          description: Observação registrada, quando existir.
        is_repaid:
          type:
            - boolean
            - 'null'
        tag:
          type:
            - string
            - 'null'
          description: Tag associada à transação.
        is_biometrics_pix:
          type:
            - boolean
            - 'null'
      required:
        - id
        - merchant_id
        - user_id
        - processor_id
        - merchant_transaction_id
        - transaction_type
        - first_name
        - last_name
        - email
        - meta
        - updated_at
        - created_at
        - document_number
        - status
        - flow_type
        - error
        - e2e_id
        - source
        - transaction_repay_id
        - responsable
        - observation
        - is_repaid
        - tag
        - is_biometrics_pix
  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.