> ## 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 aporte Pix > Cria uma cobrança Pix para aportar recursos à conta do estabelecimento. ## Comportamento observado * O Gateway seleciona o primeiro processador habilitado do tipo informado, em ordem de precedência. * Um `processor_type` ausente ou desconhecido pode resultar em HTTP 404 antes da validação dos outros campos. * O Gateway força `source` para `funding`, mesmo que outro valor seja enviado. * Endereço, nome, email e telefone podem se tornar obrigatórios conforme a configuração do processador. * Se `pix_message` não for enviado, o Gateway usa `Depósito para: {alias do processador}`. * Os limites mínimo e máximo do processador também são aplicados ao valor. > [!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/merchant/funds 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/merchant/funds: post: tags: - Pix summary: Criar aporte Pix description: Cria uma cobrança Pix para aportar recursos à conta do estabelecimento. operationId: reference_pix_create-fund 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 description: CNPJ do estabelecimento. 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: >- Campo aceito no corpo, mas o Gateway sempre grava funding nesta operação. processor_type: type: string description: Tipo do processador habilitado para o estabelecimento. required: - processor_type - amount - document_number - merchant_transaction_id example: processor_type: sandbox_pix amount: 500 document_number: '12345678000195' merchant_transaction_id: 50000000-0000-4000-8000-000000000002 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-000000000002 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: success event_type: auth amount: '500.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: 'Depósito para: CONTA DEMO' updated_at: '2026-10-23T14:30:00+00:00' created_at: '2026-10-23T14:30:00+00:00' document_number: '12345678000195' status: pending flow_type: cashin error: null e2e_id: null source: funding 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 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 '404': description: Nenhum processador habilitado corresponde ao processor_type. content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: error: message: Processor not found. status: 404 '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.