PodPay API

Navegação: na referência interativa (ex.: docs.podpay.app), os endpoints estão agrupados na barra lateral por domínio: Transactions, Withdrawals, Balance e Webhooks.

Sobre a API

A PodPay é uma plataforma completa de pagamentos e saques que permite processar transações via PIX, Cartão de Crédito e Boleto, além de realizar saques bancários (PIX) e em criptomoedas.

Funcionalidades Principais

Pagamentos

• PIX: Pagamentos instantâneos via QR Code ou código copy-paste
• Cartão de Crédito: Pagamentos com suporte a parcelamento (até 12x)
• Boleto: Pagamentos via boleto bancário com vencimento configurável

Saques

• Saques PIX: Saques bancários instantâneos via chave PIX
• Saques Cripto: Saques em criptomoedas (USDT, BTC, etc.) para carteiras externas

Gestão

• Consulta de Saldo: Visualização de saldo disponível, em liberação e reservas
• Histórico: Listagem completa de transações e saques com filtros avançados
• Webhooks: Notificações em tempo real sobre mudanças de status

Ambientes

Produção

• URL: https://api.podpay.app
• Uso: Ambiente de produção para transações reais
• API Keys: Geradas no dashboard com ambiente live

Sandbox

• URL: https://sandbox.podpay.app
• Uso: Ambiente de testes para desenvolvimento e validação
• API Keys: Geradas no dashboard com ambiente test

Autenticação e Headers

Header obrigatório de autenticação

Todas as chamadas autenticadas da API REST devem enviar:

• x-api-key: chave secreta da empresa/integrador

Exemplo:

x-api-key: sk_live_xxxxxxxxxxxxx

Headers recomendados para rastreabilidade

• X-Idempotency-Key: evita duplicidade em operações financeiras de criação
• x-correlation-id: ajuda a correlacionar logs do parceiro com os logs da PodPay
• Content-Type: application/json: obrigatório para envio de payload JSON

Informações Importantes

Valores em Centavos

⚠️ ATENÇÃO: Todos os valores monetários são enviados e retornados em centavos (inteiros).

Exemplos:

• R$ 100,00 = 10000 centavos
• R$ 1.500,50 = 150050 centavos
• R$ 0,50 = 50 centavos

Valor mínimo: R$ 1,00 (100 centavos)

Rate Limits

Transações:

• Padrão: 5 requisições por segundo por API Key (Configurável por Empresa)
• Headers de resposta incluem: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Saques:

• Padrão: 10 saques por minuto (Configurável por Empresa)

Geral:

• 60 requisições por minuto (padrão)
• Rate limit é aplicado por API Key

Idempotência (X-Idempotency-Key)

• Header recomendado em POST /v1/transactions e POST /v1/withdrawals
• Recomendado usar UUID v4 ou outra chave única estável por intento financeiro
• Um retry do mesmo pagamento ou saque deve reutilizar exatamente a mesma chave
• Repetições com a mesma chave do cliente podem retornar a mesma entidade já criada, e incluem headers como:
  • X-Idempotency-Key
  • X-Idempotency-Key-Source
  • X-Idempotency-Replayed
  • X-Idempotency-Processed-At
• Sem X-Idempotency-Key enviada pelo cliente, a API cria uma nova operação e gera apenas uma chave interna para rastreabilidade
• Com a feature flag de proteção implícita habilitada, a plataforma pode ativar fallback ou bloqueios semânticos adicionais para requests sem chave explícita
• O parceiro deve sempre reconciliar pelo id retornado e pelos webhooks, nunca apenas por "requisição respondeu com sucesso"

Por que a idempotência é importante

Sem idempotência bem implementada, um timeout, retry automático do gateway, retry manual do seller ou perda de persistência local pode gerar tentativas duplicadas do mesmo pagamento ou saque. Em operações financeiras isso pode causar:

• duplicidade local no ERP ou checkout do parceiro
• reenvio do mesmo saque com o mesmo id remoto, mas tratado como novo pelo integrador
• divergência entre pedido local, transação remota e webhook recebido
• perda de conversão por integrações que não persistem corretamente o id devolvido pela API

Formato de Resposta

Todas as respostas seguem o formato padrão:

{
  "success": true,
  "data": { /* dados da resposta */ },
  "meta": {
    "timestamp": "2024-01-01T12:00:00Z",
    "version": "v1",
    "requestId": "req_1234567890_abc123"
  }
}

Em caso de erro:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Mensagem de erro descritiva",
    "details": { /* detalhes adicionais */ }
  },
  "meta": {
    "timestamp": "2024-01-01T12:00:00Z",
    "version": "v1",
    "requestId": "req_1234567890_abc123"
  }
}

IDs e Identificadores

• Transações: Formato tx_... ou CUID
• Saques: Formato wd_... ou CUID
• Request IDs: Formato req_${timestamp}_${random}
• Event IDs: Formato evt_... (para webhooks)

Status de Transações

• pending: Aguardando pagamento
• processing: Processando pagamento
• paid: Pagamento confirmado
• failed: Pagamento falhou
• cancelled: Transação cancelada
• blocked: Transação bloqueada para análise
• refunded: Transação estornada
• pre_chargeback: Transação em pré-disputa (chargeback iniciado)
• chargeback: Transação em disputa (chargeback confirmado)

Status de Saques

• pending: Aguardando processamento
• pending_approval: Aguardando aprovação manual
• processing: Processando saque
• completed: Saque completado com sucesso
• failed: Saque falhou
• cancelled: Saque cancelado

Links Úteis

• Website: https://podpay.app
• Suporte: contato@podpay.app
• Documentação: https://docs.podpay.app
• Termos de Uso: https://www.podpay.app/docs/termos-e-condicoes

Suporte

Para dúvidas, problemas ou sugestões, entre em contato:

• Email: contato@podpay.app
• Horário de Atendimento: Segunda a Sexta, 9h às 18h (horário de Brasília)