Envio via Pix

Geração de Pix de Saída (Pix out) — GeneratePix

A geração de Pix de saída permite a criação de uma ordem de pagamento para uma conta de destino.

❗️

Importante:

O método não aceita Chave Pix. O pagamento deve ser solicitado obrigatoriamente com os dados bancários da conta destino, incluindo banco, agência, conta, dígito, nome e CPF/CNPJ do favorecido.

Após o envio da solicitação, a Owl registra a ordem de Pix e retorna um identificador da operação. Esse retorno confirma o recebimento da solicitação, mas não representa necessariamente a liquidação do Pix.

A confirmação final ocorre de forma assíncrona, por meio de webhook enviado para a URL cadastrada pelo parceiro.

O parceiro deve considerar como sucesso apenas o status Pago.

Status como Cancelado, Erro ou Rejeitado devem ser tratados como falha.

Recomenda-se armazenar o identificador retornado pela Owl e utilizar descrições ou etiquetas para facilitar a conciliação e rastreabilidade da operação.

⚠️

A documentação atual não prevê chave de idempotência para este endpoint. Por isso, em casos de timeout, instabilidade ou reenvio da solicitação, o parceiro deve adotar controles internos para evitar pagamentos duplicados.

Endpoint

POST {BASE_URL}/boleto-app/api/Pix/GeneratePix

Headers

Header	Valor
Authorization	Basic {base64(usuario:senha)}
Content-Type	application/json

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
clientId	number	Sim	Identificador do parceiro (cliente) na Owl.
toName	string	Sim	Nome do favorecido (destino).
toTaxId	string	Sim	CPF/CNPJ do favorecido.
toBank	string	Sim	Código do banco de destino (ISPB/COMPE).
toBankBranch	string	Sim	Agência de destino.
toBankAccount	string	Sim	Conta de destino.
toBankAccountDigit	string	Sim	Dígito da conta de destino.
toBankName	string	Não	Nome do banco de destino.
value	number	Sim	Valor do Pix (decimal, em reais).
paymentDate	string (date-time)	Sim	Data/hora de execução do pagamento (ISO 8601).
description	string	Não	Descrição interna da operação.
customerMessage	string	Não	Mensagem exibida ao favorecido.
tags	string[]	Não	Etiquetas livres para conciliação.

Exemplo de request (campos opcionais comentados)

jsonc

{
  // ---- obrigatórios ----
  "clientId": 1024,
  "toName": "Maria Souza",
  "toTaxId": "12345678909",
  "toBank": "341",
  "toBankBranch": "0001",
  "toBankAccount": "98765",
  "toBankAccountDigit": "0",
  "value": 150.75,
  "paymentDate": "2026-06-07T12:00:00",

  // ---- opcionais ----
  "toBankName": "Itaú Unibanco",                 // não obrigatório
  "description": "Repasse parceiro #4421",       // não obrigatório (uso interno)
  "customerMessage": "Pagamento do pedido 4421", // não obrigatório (mensagem ao favorecido)
  "tags": ["repasse", "pedido-4421"]             // não obrigatório
}

Observação: o JSON acima usa comentários apenas para documentação. No envio real, remova os comentários (JSON puro).

Exemplo com cURL

Bash

curl -X POST "{BASE_URL}/boleto-app/api/Pix/GeneratePix" \
  -H "Authorization: Basic $(printf '%s' 'usuario:senha' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": 1024,
    "toName": "Maria Souza",
    "toTaxId": "12345678909",
    "toBank": "341",
    "toBankBranch": "0001",
    "toBankAccount": "98765",
    "toBankAccountDigit": "0",
    "toBankName": "Itaú Unibanco",
    "value": 150.75,
    "paymentDate": "2026-06-07T12:00:00",
    "description": "Repasse parceiro #4421",
    "customerMessage": "Pagamento referente ao pedido 4421",
    "tags": ["repasse", "pedido-4421"]
  }'

Resposta

Todas as respostas usam o envelope padrão { success, data, message }.

200 — Sucesso

JSON

{
  "success": true,
  "data": {
    "pixId": 2108,
    "documentNumber": 887766,
    "url": "https://{BASE_URL}/comprovantes/pix/2108"
  },
  "message": null
}

Campo (data)	Tipo	Descrição
pixId	number	Identificador do Pix na Owl. Use-o para consultar o status em GET /Pix/GetPix/{pixId}.
documentNumber	number	Número do documento da operação no bancarizador.
url	string	URL do comprovante.

Erro (ex.: 400 / 403 / 503)

JSON

{
  "success": false,
  "data": null,
  "message": "Erro ao gerar Pix: Falha na integração. Verifique os dados informados."
}

Código	Quando
403	Credenciais inválidas ou parceiro não autorizado.
400 / 503	Dados inválidos ou falha na integração com o bancarizador.

Status possíveis do Pix

Existem dois níveis de status:

1. GET /Pix/GetPix/{pixId} — status interno da Owl. Apenas dois valores:

Status	Significado
Open	Criado, aguardando o retorno do bancarizador.
Closed	Encerrado (webhook recebido e cliente notificado).

2. Campo status do webhook — status do bancarizador, repassado como recebido. Valores possíveis:

Status	Significado
Created	Criado (não dispara atualização).
Generated	Gerado.
Registered	Registrado.
Paid	Pago (sucesso).
Cancel	Cancelado.
Error	Erro.
Registering	Registrando.
Rejected	Rejeitado.

Notificação assíncrona (webhook)

Quando o Pix é liquidado, a Owl envia um POST para a sua UrlPix cadastrada (com Basic Auth de saída) contendo o resultado:

JSON

{
  "pixId": 2108,
  "status": "Paid",
  "totalValue": 150.75,
  "creditedValue": 150.75,
  "rateValue": 0.00,
  "paymentDate": "2026-06-07T12:00:03",
  "toName": "Maria Souza",
  "toTaxNumber": "12345678909",
  "toBankCode": "341",
  "toBankBranch": "0001",
  "toBankAccount": "98765",
  "toBankAccountDigit": "0",
  "fromName": "Empresa X LTDA",
  "fromTaxNumber": "12345678000190",
  "fromBankCode": "...",
  "fromBankBranch": "...",
  "fromBankAccount": "...",
  "fromBankAccountDigit": "...",
  "errorCode": null,
  "errorDescription": null
}

Consulta de status sob demanda: GET {BASE_URL}/boleto-app/api/Pix/GetPix/{pixId} retorna { "status": "...", "url": "..." }.