Documentação Oficial

API XPayUp para Integrações

Configure sua integração em poucos passos, com segurança de ponta a ponta, webhooks assinados e fluxo pronto para cobrança, transferência, automação e operação de mensageria em produção.

Ver Passo a Passo Ver Endpoints

Checklist Rápido

  • Gerar API Key no painel
  • Configurar webhook URL
  • Rotacionar e salvar segredo HMAC
  • Testar callback assinado
  • Liberar somente IPs confiáveis

Fluxos avançados: automação, IA e billing

Com a integração pronta, seu time pode acionar comunicações, análises e controle de consumo sem sair da operação financeira.

Dispare automações por evento de cobrança e status
Use IA para análise financeira e detecção de risco
Ative canais de mensagem no fluxo de cobrança
Classifique mensagens entre sistema e solicitadas
Monitore consumo mensal por canal e trigger
Configure alertas de limite para evitar bloqueios

Passo a Passo de Configuração

Siga a ordem abaixo para seu sistema funcionar corretamente sem falhas de autenticação ou webhook.

1

Acesse API e Integrações

No painel do usuário, abra a seção API e Integrações.

Menu: API e Integrações → tela de credenciais e webhook.

2

Gere sua API Key

Crie uma chave com nome identificável, como ERP Produção.

A chave é exibida apenas uma vez. Salve em local seguro (cofre de segredos).

3

Defina o Webhook URL

Informe a URL pública do seu sistema que receberá eventos do XPayUp.

Exemplo: https://api.seusistema.com/payflow/webhook

4

Rotacione o Segredo

Clique em Rotacionar segredo e copie o valor gerado.

Use este segredo para validar assinatura HMAC dos webhooks.

5

Restrinja IPs

Adicione IPs permitidos para chamadas da API externa.

Sem allowlist correta, a API retorna 403.

6

Ative e Teste

Com integração ativa, teste:

Conta, criação de cobrança, transferência e callback assinado.

Regras de Segurança Obrigatórias

Esses itens garantem integridade, rastreabilidade e proteção contra abuso.

Autenticar com Authorization: Bearer pf_...
Nunca expor API Key no frontend
Validar assinatura sha256=... em todo webhook
Validar timestamp para bloquear replay
Aplicar allowlist de IP para consumo da API
Rotacionar chave e segredo periodicamente

Endpoints Principais

Base URL: https://www.xpayup.com.br/api/v1/payflow

Método Endpoint Finalidade
GET/meConsultar conta e links úteis
GET/chargesListar cobranças
POST/chargesCriar cobrança (PIX, cartão, boleto)
GET/charges/{transactionId}Detalhar cobrança
GET/transfersListar transferências
POST/transfersSolicitar transferência

Exemplo: criar cobrança PIX

curl -X POST "https://www.xpayup.com.br/api/v1/payflow/charges" \
  -H "Authorization: Bearer pf_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 59.90,
    "method": "pix",
    "description": "Pedido #1001",
    "customer_email": "cliente@dominio.com",
    "customer_name": "Cliente Final"
  }'

Exemplo: validar assinatura webhook

$timestamp = $_SERVER['HTTP_X_XPAYUP_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_XPAYUP_SIGNATURE'] ?? '';
$rawBody = file_get_contents('php://input');
$secret = getenv('XPAYUP_WEBHOOK_SECRET');

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('invalid signature');
}

Checklist de Go-Live

Antes de ir para produção, confirme todos os itens abaixo.

API Key de produção criada e chave antiga revogada
Webhook URL pública com HTTPS ativo
Segredo webhook salvo e validado
Callback válido retorna 200 e inválido retorna 401
Allowlist de IP aplicada
Logs e alertas de falha habilitados
Abrir API e Integrações Preciso de suporte técnico