Comprovante de pagamento (PDF)

Nesta seção, você aprenderá como gerar e baixar comprovantes em PDF de pagamentos (payouts) realizados.

Endpoint Disponível

• Sandbox: https://sandbox.pixtopay.com.br/v2/payout/receipt
• Produção: https://api.pixtopay.com.br/v2/payout/receipt

Obter comprovante em PDF

Gere e baixe o comprovante de um pagamento aprovado em formato PDF.

Route

GET /v2/payout/receipt

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

⚠️ Importante: Use apenas um dos parâmetros abaixo (não ambos):

* Use apenas id OU transaction_id, nunca ambos

Exemplo de requisição por ID:

curl --location 'https://api.pixtopay.com.br/v2/payout/receipt?id=685' \
--header 'Authorization: API_KEY' \
--output comprovante.pdf

Exemplo de requisição por transaction_id:

curl --location 'https://api.pixtopay.com.br/v2/payout/receipt?transaction_id=12345678911' \
--header 'Authorization: API_KEY' \
--output comprovante.pdf

Resposta 200 - Sucesso:

A resposta será um arquivo PDF em formato binário.

Headers da resposta:

{
  "Content-Type": "application/pdf",
  "Content-Disposition": "inline; filename='payout_E20018183202507030306IVCXWQNh0fQ.pdf'"
}

O nome do arquivo é retornado no header Content-Disposition.

Resposta 400 - Parâmetros inválidos:

{
  "type": "ValidationError",
  "message": "Use only id or transaction_id, not both"
}

Resposta 404 - Pagamento não encontrado:

{
  "message": "Payout not found"
}

Resposta 400 - Pagamento não aprovado:

{
  "type": "ValidationError",
  "message": "Receipt is only available for paid payouts"
}

Requisitos

Para gerar um comprovante, o pagamento deve atender aos seguintes requisitos:

• ✅ Status aprovado: O pagamento deve ter status 1 (aprovado/concluído)
• ✅ Processamento concluído: O campo paid_at deve estar preenchido
• ✅ Identificação válida: Fornecer id ou transaction_id válido

Usando em aplicações web

JavaScript/TypeScript

async function downloadReceipt(transactionId) {
  const response = await fetch(
    `https://api.pixtopay.com.br/v2/payout/receipt?transaction_id=${transactionId}`,
    {
      headers: {
        Authorization: "YOUR_API_KEY",
      },
    }
  );
 
  if (response.ok) {
    const blob = await response.blob();
    const url = window.URL.createObjectURL(blob);
    const a = document.createElement("a");
    a.href = url;
    a.download = "comprovante.pdf";
    document.body.appendChild(a);
    a.click();
    a.remove();
  }
}

Python

import requests
 
def download_receipt(transaction_id):
    url = f"https://api.pixtopay.com.br/v2/payout/receipt?transaction_id={transaction_id}"
    headers = {
        "Authorization": "YOUR_API_KEY"
    }
 
    response = requests.get(url, headers=headers)
 
    if response.status_code == 200:
        with open("comprovante.pdf", "wb") as f:
            f.write(response.content)
        print("Comprovante baixado com sucesso!")
    else:
        print(f"Erro: {response.json()}")

PHP

<?php
$transactionId = "12345678911";
$url = "https://api.pixtopay.com.br/v2/payout/receipt?transaction_id=" . $transactionId;
 
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: YOUR_API_KEY'
]);
 
$output = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
if ($httpCode === 200) {
    file_put_contents("comprovante.pdf", $output);
    echo "Comprovante baixado com sucesso!";
} else {
    echo "Erro ao baixar comprovante";
}
?>

Informações do Comprovante

O comprovante em PDF contém as seguintes informações:

• 📄 Dados do pagamento: Valor, data e hora
• 👤 Dados do beneficiário: Nome, documento
• 🏦 Dados bancários: Banco, agência, conta
• 🔐 Identificadores: Transaction ID, ID interno
• ✅ Comprovação: Hash da transação e status

Observações Importantes

• Disponibilidade: Comprovantes estão disponíveis apenas para pagamentos com status 1 (aprovado)
• Formato: O arquivo é retornado em formato PDF padrão
• Tamanho: Geralmente entre 50KB e 200KB
• Validade: O comprovante tem validade legal e pode ser usado como comprovante de pagamento
• Geração: O comprovante é gerado em tempo real a cada requisição
• Cache: Não há necessidade de fazer cache local, o endpoint sempre retornará o mesmo PDF para o mesmo pagamento

Casos de Uso

1. Portal do cliente

Permita que seus clientes baixem comprovantes de pagamentos recebidos

2. Sistemas de contabilidade

Integre com seu sistema de contabilidade para arquivo automático de comprovantes

3. Envio por email

Envie comprovantes automaticamente por email após aprovação do pagamento

4. Auditoria

Mantenha registros de todos os pagamentos realizados com seus respectivos comprovantes