🚀 Porto Payments API

Documentação completa da API de pagamentos PIX

📖 Introdução

Bem-vindo à API do Porto Payments! Nossa API permite que você integre pagamentos PIX de forma simples e segura em seu sistema.

🌐 URL Base

https://api.portopag.com/api/v1/

✨ Recursos Principais

  • Criar pagamentos PIX instantâneos
  • Consultar status de pagamentos
  • Listar todos os pagamentos
  • Consultar saldo e informações da conta
  • Receber notificações em tempo real via webhooks

🔐 Autenticação

Todas as requisições à API devem incluir sua chave de API no header Authorization usando o esquema Bearer.

As chaves de API seguem o formato: ppay_xxxxxxxxx_yyyyyyy

Como obter sua API Key

  1. Acesse app.portopag.com
  2. Vá em Configurações → API
  3. Copie ou gere uma nova API Key

Exemplo de Header

Authorization: Bearer ppay_abc123def_45678xyz
Content-Type: application/json
⚠️ Importante: Nunca compartilhe sua API Key publicamente ou em repositórios Git. Guarde-a em variáveis de ambiente.

🎯 Endpoints

Criar Pagamento PIX

POST /payments

Cria um novo pagamento PIX e retorna o código QR e código Pix Copia e Cola.

Parâmetros

Campo Tipo Status Descrição
amount integer obrigatório Valor em centavos (ex: 15000 = R$ 150,00)
customer object obrigatório Dados do cliente (name, email, cpf, phone)
customer.name string obrigatório Nome completo do cliente
customer.email string obrigatório Email do cliente
customer.cpf string obrigatório CPF com 11 dígitos (apenas números)
customer.phone string obrigatório Telefone 11 dígitos (formato: 11999999999)
paymentMethod string obrigatório Deve ser "pix"
items array obrigatório Lista de items do pagamento
items[].unitPrice integer obrigatório Preço unitário em centavos
items[].title string obrigatório Nome/título do item
items[].quantity integer obrigatório Quantidade do item
items[].tangible boolean opcional Se é produto físico (padrão: false)
utmQuery string opcional Parâmetros UTM para rastreamento
checkoutUrl string opcional URL do checkout
postbackUrl string opcional URL para receber notificações (específica desta transação)
externalId string opcional ID externo do seu sistema
referrerUrl string opcional URL de origem da compra
shipping object opcional Endereço de entrega (para produtos físicos)
fingerPrints array opcional Array de fingerprints (provider, value) para rastrear dispositivo/IP
💡 Importante: O campo amount deve ser igual à soma de items[].unitPrice * items[].quantity.

Exemplo de Resposta

{
  "success": true,
  "data": {
    "transaction_id": "PPAY1731356789abc12345",
    "pix_code": "00020126580014br.gov.bcb.pix...",
    "qr_code_image": "data:image/png;base64,iVBORw0KGgo...",
    "amount": 150.00,
    "status": "pending",
    "expires_at": "2024-11-11T05:00:00Z",
    "created_at": "2024-11-11T04:00:00Z"
  },
  "timestamp": "2024-11-11T04:00:00Z",
  "request_id": "req_1699678912345_a1b2c3"
}

Consultar Pagamento Específico

GET /payments/:transaction_id

Consulta o status de um pagamento específico pelo transaction ID.

Parâmetros de URL

Parâmetro Descrição
transaction_id ID da transação (formato: PPAY...)

Exemplo de Resposta

{
  "success": true,
  "data": {
    "transaction_id": "PPAY1731356789abc12345",
    "status": "paid",
    "amount": 150.00,
    "customer_name": "João Silva",
    "customer_cpf": "12345678900",
    "paid_at": "2024-11-11T04:30:00Z",
    "created_at": "2024-11-11T04:00:00Z"
  },
  "timestamp": "2024-11-11T04:35:00Z"
}

Listar Todos os Pagamentos

GET /payments

Retorna uma lista de todos os pagamentos da sua conta.

Parâmetros de Query (opcionais)

Parâmetro Tipo Descrição
status string Filtrar por status (pending, paid, expired, cancelled)
limit number Quantidade de resultados (padrão: 50, máximo: 100)
offset number Paginação - quantidade de registros a pular

Exemplo de Resposta

{
  "success": true,
  "data": {
    "payments": [
      {
        "transaction_id": "PPAY1731356789abc12345",
        "status": "paid",
        "amount": 150.00,
        "customer_name": "João Silva",
        "created_at": "2024-11-11T04:00:00Z",
        "paid_at": "2024-11-11T04:30:00Z"
      },
      {
        "transaction_id": "PPAY1731356790xyz67890",
        "status": "pending",
        "amount": 75.50,
        "customer_name": "Maria Santos",
        "created_at": "2024-11-11T03:45:00Z",
        "paid_at": null
      }
    ],
    "total": 2,
    "limit": 50,
    "offset": 0
  },
  "timestamp": "2024-11-11T04:35:00Z"
}

Consultar Saldo e Informações da Conta

GET /account

Retorna o saldo disponível, em processamento e informações da conta.

Exemplo de Resposta

{
  "success": true,
  "data": {
    "balance": {
      "available": 1500.00,
      "pending": 350.00,
      "total_fees": 45.50
    },
    "account": {
      "user_id": 123,
      "username": "empresa@exemplo.com",
      "created_at": "2024-01-15T10:00:00Z"
    },
    "statistics": {
      "total_transactions": 25,
      "total_paid": 20,
      "total_pending": 3,
      "total_expired": 2
    }
  },
  "timestamp": "2024-11-11T04:35:00Z"
}

Consultar Status Público (Sem Autenticação)

GET /public/status/:transaction_id

Consulta o status de um pagamento sem necessidade de autenticação. Ideal para páginas de checkout públicas.

💡 Info: Este endpoint não requer o header Authorization e pode ser chamado diretamente do navegador do cliente.

Parâmetros de URL

Parâmetro Descrição
transaction_id ID da transação (formato: PPAY...)

Exemplo de Resposta

{
  "success": true,
  "data": {
    "transaction_id": "PPAY1731356789abc12345",
    "status": "paid",
    "amount": 150.00,
    "paid_at": "2024-11-11T04:30:00Z"
  },
  "timestamp": "2024-11-11T04:35:00Z"
}

🔔 Webhooks

Webhooks permitem que você receba notificações em tempo real sobre mudanças de status nos pagamentos.

Configurar Webhook

O endpoint de webhook é configurado pelo usuário diretamente no painel de controle:

  1. Acesse app.portopag.com
  2. Vá em Configurações → Webhooks
  3. Adicione a URL do seu servidor: https://seu-sistema.com/webhook
  4. Selecione os eventos desejados
  5. Salve as configurações

Eventos Disponíveis

Evento Descrição
payment.paid Pagamento aprovado e confirmado
payment.pending Novo pagamento criado aguardando confirmação
payment.failed Pagamento falhou ou foi cancelado
payment.expired Pagamento expirou sem confirmação

Payload do Webhook

Os eventos enviados incluem o transaction ID no formato PPAY seguido de timestamp e caracteres aleatórios:

{
  "event": "payment.paid",
  "transaction_id": "PPAY1731356789abc12345",
  "amount": 150.00,
  "customer_name": "João Silva",
  "customer_cpf": "12345678900",
  "customer_email": "joao@email.com",
  "paid_at": "2024-11-11T04:30:00Z",
  "created_at": "2024-11-11T04:00:00Z",
  "external_id": "seu-id-externo",
  "timestamp": "2024-11-11T04:30:05Z"
}
💡 Dica: Sempre responda com status 200 OK para confirmar o recebimento do webhook. Se não responder em até 5 segundos, faremos até 3 tentativas de reenvio.

Exemplo de Implementação do Webhook

// Node.js/Express exemplo
app.post('/webhook', (req, res) => {
  const { event, transaction_id, amount, paid_at } = req.body;
  
  if (event === 'payment.paid') {
    console.log(`Pagamento ${transaction_id} confirmado!`);
    console.log(`Valor: R$ ${amount}`);
    // Processar o pagamento no seu sistema
  }
  
  // IMPORTANTE: Sempre retornar 200 OK
  res.status(200).json({ received: true });
});

❌ Códigos de Erro

Código HTTP Código de Erro Descrição Solução
400 VALIDATION_ERROR Dados de entrada inválidos Verifique os parâmetros enviados
401 UNAUTHORIZED API Key inválida ou ausente Verifique se o header Authorization está correto
404 NOT_FOUND Pagamento não encontrado Verifique se o transaction_id está correto
429 RATE_LIMIT_EXCEEDED Limite de requisições excedido Aguarde antes de fazer novas requisições
500 INTERNAL_ERROR Erro interno do servidor Tente novamente em alguns minutos

Exemplo de Resposta de Erro

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dados de entrada inválidos",
    "details": "amount: Valor deve ser maior que R$ 0,01"
  },
  "timestamp": "2024-11-11T04:35:00Z",
  "request_id": "req_1699678912345_a1b2c3"
}

💻 Exemplos de Código

Criar Pagamento PIX

curl -X POST https://api.portopag.com/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ppay_abc123def_45678xyz" \
  -d '{
    "amount": 15000,
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "cpf": "12345678900",
      "phone": "11999999999"
    },
    "paymentMethod": "pix",
    "items": [
      {
        "unitPrice": 15000,
        "title": "Produto Premium",
        "quantity": 1,
        "tangible": false
      }
    ],
    "utmQuery": "utm_source=google&utm_medium=cpc",
    "checkoutUrl": "https://checkout.portopag.com/abc123",
    "externalId": "pedido_12345"
  }'
const response = await fetch('https://api.portopag.com/api/v1/payments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ppay_abc123def_45678xyz'
  },
  body: JSON.stringify({
    amount: 15000, // R$ 150,00 em centavos
    customer: {
      name: "João Silva",
      email: "joao@email.com",
      cpf: "12345678900",
      phone: "11999999999"
    },
    paymentMethod: "pix",
    items: [
      {
        unitPrice: 15000,
        title: "Produto Premium",
        quantity: 1,
        tangible: false
      }
    ],
    utmQuery: "utm_source=google&utm_medium=cpc",
    checkoutUrl: "https://checkout.portopag.com/abc123",
    externalId: "pedido_12345"
  })
});

const result = await response.json();
console.log('Transaction ID:', result.data.transaction_id);
console.log('PIX Code:', result.data.pix_code);
console.log('QR Code:', result.data.pix_qr_code);
import requests

url = "https://api.portopag.com/api/v1/payments"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer ppay_abc123def_45678xyz"
}
data = {
    "amount": 15000,  # R$ 150,00 em centavos
    "customer": {
        "name": "João Silva",
        "email": "joao@email.com",
        "cpf": "12345678900",
        "phone": "11999999999"
    },
    "paymentMethod": "pix",
    "items": [
        {
            "unitPrice": 15000,
            "title": "Produto Premium",
            "quantity": 1,
            "tangible": False
        }
    ],
    "utmQuery": "utm_source=google&utm_medium=cpc",
    "checkoutUrl": "https://checkout.portopag.com/abc123",
    "externalId": "pedido_12345"
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

print(f"Transaction ID: {result['data']['transaction_id']}")
print(f"PIX Code: {result['data']['pix_code']}")
print(f"QR Code: {result['data']['pix_qr_code']}")
<?php
$url = "https://api.portopag.com/api/v1/payments";
$data = [
    "amount" => 15000, // R$ 150,00 em centavos
    "customer" => [
        "name" => "João Silva",
        "email" => "joao@email.com",
        "cpf" => "12345678900",
        "phone" => "11999999999"
    ],
    "paymentMethod" => "pix",
    "items" => [
        [
            "unitPrice" => 15000,
            "title" => "Produto Premium",
            "quantity" => 1,
            "tangible" => false
        ]
    ],
    "utmQuery" => "utm_source=google&utm_medium=cpc",
    "checkoutUrl" => "https://checkout.portopag.com/abc123",
    "externalId" => "pedido_12345"
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer ppay_abc123def_45678xyz"
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

echo "Transaction ID: " . $result['data']['transaction_id'] . "\n";
echo "PIX Code: " . $result['data']['pix_code'] . "\n";
echo "QR Code: " . $result['data']['pix_qr_code'] . "\n";
?>

Consultar Status de Pagamento

// JavaScript exemplo - consulta autenticada
const transactionId = "PPAY1731356789abc12345";
const response = await fetch(
  `https://api.portopag.com/api/v1/payments/${transactionId}`,
  {
    headers: {
      'Authorization': 'Bearer ppay_abc123def_45678xyz'
    }
  }
);
const payment = await response.json();
console.log('Status:', payment.data.status);

// JavaScript exemplo - consulta pública (sem autenticação)
const publicResponse = await fetch(
  `https://api.portopag.com/api/v1/public/status/${transactionId}`
);
const publicPayment = await publicResponse.json();
console.log('Status público:', publicPayment.data.status);
✅ Pronto! Agora você está pronto para integrar pagamentos PIX em sua aplicação.