WINNERPAY API - DOCUMENTAÇÃO COMPLETA

Bem-vindo à WinnerPay
Documentação oficial da API de pagamentos e transferências PIX do WinnerPay — Gateway para Vencedores.

Copiar link da página
Bem-vindo à documentação da WinnerPay
Aqui você encontra tudo que precisa para integrar sua aplicação à nossa plataforma de pagamentos. Navegue pelos módulos abaixo para começar.
Antes de começar, certifique-se de que você possui uma conta ativa na WinnerPay e suas credenciais de acesso à API aprovadas. Caso ainda não tenha, acesse o Dashboard para criar sua conta.

Como funciona a integração
O WinnerPay atua como uma camada intermediária entre seu sistema e as adquirentes de pagamento. Quando você cria uma transação PIX, o sistema:
Busca a adquirente ativa configurada no sistema
Cria a transação internamente no WinnerPay
Chama a API da adquirente ativa para processar o pagamento
Retorna os dados do QR Code/cobrança para o checkout
Recebe notificações via webhook da adquirente
Normaliza os webhooks para um formato único e padronizado
Envia webhook normalizado para seu endpoint configurado
Atualiza o status da transação automaticamente
Importante: Você pode trocar de adquirente a qualquer momento SEM precisar alterar seu código! Todos os webhooks que você receberá seguem o mesmo formato independente da adquirente.

Comece por aqui
AutenticaçãoSaiba como gerar suas chaves de API e autenticar requisições com segurança.WebhooksEntenda como receber notificações em tempo real sobre eventos da sua conta.Gere sua primeira vendaCrie um QR Code PIX e receba pagamentos imediatamente via API.Solicite um saqueTransfira saldo para qualquer chave PIX diretamente via API.Configure split paymentCrie cobranças PIX com divisão entre vendedor, plataforma e gateway.
Base URL
URLCopiar
```
https://api.winnerpayy.com.br/api
```

================================================================================

[Guia de Implementação] Autenticação
Como autenticar suas requisições à API WinnerPay usando Client Credentials.

Client Credentials
Para utilizar nossa API, você precisa de suas credenciais client_id e client_secret. Estas credenciais são geradas no painel WinnerPay, na seção API → Credenciais.
Nunca exponha suas credenciais no client-side. As chamadas devem sempre partir do seu servidor backend.

Opção 1 — Authorization Header (recomendado)
HTTP HeaderCopiar
```
Authorization: Basic {base64(client_id:client_secret)}
```

Opção 2 — Headers separados
HTTP HeadersCopiar
```
X-Client-Id: seu_client_id
X-Client-Secret: seu_client_secret
```

Autenticação do painel (Bearer Token)
Para endpoints do dashboard, use o Bearer Token obtido via login:
HTTP HeaderCopiar
```
Authorization: Bearer seu_jwt_token
```

Registrar usuário
POST/api/auth/registerCampoTipoObrig.Descrição
namestringreqNome completo
emailstringreqE-mail único
passwordstringreqMínimo 8 caracteres
usernamestringreqUsername único
phonestringoptTelefone
cnpjstringoptCNPJ da empresa
Response 200Copiar
```
{
"success": true,
"token": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": 1,
"name": "João Silva",
"email": "joao@email.com",
"kyc_status": "pending",
"is_sandbox": true
}
}
```

================================================================================

[Guia de Implementação] Webhooks
Como receber notificações em tempo real sobre mudanças de status das suas transações.

Como funcionam os Webhooks
Os webhooks são enviados automaticamente para a URL configurada no campo postbackUrl ao criar uma transação.
O WinnerPay normaliza os webhooks de TODAS as adquirentes para um formato único. Independente da adquirente conectada, você sempre receberá o mesmo formato padronizado.

Fluxo de entrega
Adquirente → envia webhook no formato dela ↓WinnerPay → recebe, normaliza e processa ↓Seu Endpoint → recebe webhook no formato padronizado WinnerPay
Verificação de assinatura HMAC
Todos os webhooks enviados incluem o header X-WinnerPay-Signature para validação:
Node.js — VerificaçãoCopiar
```
const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(JSON.stringify(body))
.digest('hex');
return `sha256=${expected}` === signature;
}
```

Payload — Pagamento recebido (cash_in)
JSON PayloadCopiar
```
{
"event": "transaction.status.updated",
"transaction_id": "TXN_1697123456_ABC12345",
"external_id": "TXN_1697123456_ABC12345",
"acquirer_transaction_id": "PIXUP123456789",
"status": "paid",
"previous_status": "pending",
"amount": 150.00,
"fee": 4.50,
"total_amount": 154.50,
"type": "cash_in",
"payment_method": "PIX",
"payer": {
"name": "João Silva",
"email": "joao@email.com",
"document": "12345678900"
},
"created_at": "2025-03-28T12:00:00.000Z",
"updated_at": "2025-03-28T12:05:23.000Z"
}
```

Eventos disponíveis
transaction.createdTransação criadatransaction.status.updatedStatus atualizadotransaction.completedCompletada com sucessotransaction.processingEm processamentotransaction.refusedRecusadatransaction.failedFalhoutransaction.refundedEstornadatransaction.cancelledCancelada

================================================================================

[Guia de Implementação] Sandbox
Ambiente de testes para desenvolvimento e homologação.

Modo Sandbox
Toda conta nova entra automaticamente em modo Sandbox até a aprovação dos documentos KYC. No sandbox, nenhuma transação real é processada.
No ambiente Sandbox, as credenciais contêm test no lugar de live. Os webhooks são simulados localmente.

Identificar ambiente
O campo is_sandbox na resposta do login e kyc_status indicam o estado da conta:
GET /api/auth/meCopiar
```
{
"kyc_status": "pending",  // pending | approved | rejected
"is_sandbox": true         // false quando aprovado
}
```

================================================================================

[Cash In — Receber PIX] Regras de contrato
Regras e limites para recebimento via PIX.

Regras de contrato
Valor mínimo: R$ 0,01
Valor máximo por transação: conforme limite da adquirente ativa
Taxa: cobrada conforme acordado no contrato
Prazo de liquidação: instantâneo após confirmação
QR Code expira em: 30 minutos (padrão)
Idempotência: cada transaction_id é único

================================================================================

[Cash In — Receber PIX] Webhook de pagamento
Notificação enviada quando um pagamento PIX é confirmado.

Evento: transaction.status.updated
Enviado ao seu postbackUrl quando o status de um recebimento muda. Responda com HTTP 200 para confirmar recebimento.
JSON Payload — Pagamento confirmadoCopiar
```
{
"event": "transaction.status.updated",
"transaction_id": "TXN_1697123456_XYZ98765",
"status": "paid",
"previous_status": "pending",
"amount": 150.00,
"fee": 4.50,
"type": "cash_in",
"payment_method": "PIX",
"payer": {
"name": "João Silva",
"email": "joao@email.com",
"document": "12345678900"
},
"metadata": {
"acquirer": "pixup_1",
"original_status": "PAID"
},
"created_at": "2025-03-28T12:00:00.000Z",
"updated_at": "2025-03-28T12:05:23.000Z"
}
```

================================================================================

[Cash In — Receber PIX] POST Gerar QR Code PIX
Crie uma cobrança PIX e receba pagamentos instantâneos.

POST/api/financial/receber-pixGera um QR Code PIX para receber pagamentos. O postbackUrl recebe notificações de status automaticamente. Mesmos caminhos da documentação v1 e do Swagger em /api/docs (API v2): um único endpoint, sem quebrar integrações antigas.
ℹ️Coluna “Produto” no painel WinnerPay usa o que for enviado aqui: o ideal é metadata.product.name (doc v1) ou o atalho product_name / product na raiz (também aceitos). Só metadata.order_id não traz nome de produto — o painel mostra apenas a referência “Ordem …”. Inclua nome via description, items[].title ou payerQuestion se preferir.
Parâmetros
CampoTipoObrig.Descrição
amountfloatoptValor em R$ (0 = QR dinâmico)
descriptionstringoptDescrição do pagamento
postbackUrlstringoptURL para receber notificações webhook
metadataobjectoptDados adicionais (ex.: order_id, product: { name })
user_metadataobjectoptMesclado com metadata (atalho no body)
productstring | objectoptAtalho na raiz; string vira { name }
product_namestringoptAtalho na raiz = nome do produto (painel)
customerobjectoptDados do pagador (nome, CPF, email, endereço)
itemsarrayoptItens da cobrança
payerobjectoptFormato simplificado do pagador
external_idstringoptID externo para referência
payerQuestionstringoptTexto exibido ao pagador (opcional)
Request BodyCopiar
```
{
"amount": 150.00,
"description": "Pagamento do Plano Premium",
"postbackUrl": "https://meu-servidor.com/webhook/winnerpay",
"metadata": {
"order_id": "ORD-12345",
"product": { "name": "Plano Premium" }
},
"customer": {
"name": "João Silva",
"email": "joao@email.com",
"document": { "type": "CPF", "number": "12345678900" }
}
}
```
Response 200Copiar
```
{
"success": true,
"message": "QR Code PIX gerado com sucesso",
"transaction": {
"id": 1,
"transaction_id": "TXN_1697123456_XYZ98765",
"type": "receber_pix",
"status": "pending",
"amount": 150.00,
"fee": 0.00,
"created_at": "2025-03-28T12:00:00.000Z"
},
"pix_key": "contato@winnerpay.com.br",
"qr_code_data": "PIX_TXN_1697123456_XYZ98765",
"pix_copia_e_cola": "PIX_TXN_1697123456_XYZ98765",
"acquirer": "PIX UP"
}
```

================================================================================

[Cash In — Receber PIX] GET Listar transações
Consulte o histórico paginado de todas as transações da conta.

GET/api/financial/transactionsQueryTipoDefaultDescrição
pageint1Página atual
per_pageint15Itens por página
Response 200Copiar
```
{
"success": true,
"transactions": {
"current_page": 1,
"data": [
{
"id": 1,
"transaction_id": "TXN_...",
"type": "receber_pix",
"status": "pending",
"amount": 150.00,
"description": "Pagamento do Plano Premium",
"metadata": { /* gravado na criação */ },
"product_name": "Plano Premium",
"created_at": "2025-03-28T12:00:00.000Z",
"updated_at": "2025-03-28T12:00:00.000Z"
}
],
"total": 50,
"per_page": 15,
"last_page": 4
}
}
```

================================================================================

[Cash In — Receber PIX] POST Estornar transação
Estorne uma transação paga ou completada.

POST/api/financial/estornar/{transactionId}Apenas transações com status paid ou completed podem ser estornadas. Transferências PIX não podem ser estornadas.
Response 200Copiar
```
{
"success": true,
"message": "Transação estornada com sucesso",
"transaction": {
"transaction_id": "TXN_1697123456_ABC12345",
"status": "refunded",
"amount": 100.50
}
}
```
Response 400Copiar
```
{
"success": false,
"message": "Apenas transações pagas/completas podem ser estornadas"
}
```

================================================================================

[Cash In — Receber PIX] GET Dados do Seller
Retorna os dados cadastrais da empresa vinculada às credenciais.

GET/api/sellerResponse 200Copiar
```
{
"success": true,
"seller": {
"id": 123,
"company_name": "ACME LTDA",
"document": { "type": "CNPJ", "number": "12345678000190" },
"email": "contato@acme.com.br",
"phone": "11999999999",
"address": {
"zipCode": "01001000",
"city": "São Paulo",
"state": "SP"
},
"status": "approved"
}
}
```

================================================================================

[Split] POST Split Payment
Crie uma cobrança PIX com divisão configurada entre múltiplos recebedores.

Indicado para marketplaces e plataformas SaaS: o cliente final paga uma vez e a configuração de repasse fica vinculada à transação para auditoria, conciliação e processamento conforme a adquirente habilitada.
POST/api/transactions/splitCria uma cobrança PIX com o valor total em centavos e registra a divisão em splits. A soma das parcelas deve ser exatamente igual ao valor total enviado em amount. O valor mínimo para criar uma transação de split é R$ 3,00 (300 centavos).
CampoTipoObrig.Descrição
amountintegerreqValor total da cobrança em centavos. Mínimo: 300.
splitsarrayreqLista de recebedores e respectivos valores em centavos.
splits[].recipientstringreqIdentificador/chave PIX do recebedor.
splits[].amountintegerreqParcela do recebedor em centavos.
descriptionstringoptDescrição da cobrança PIX.
postbackUrlstringoptWebhook para atualização de status da cobrança.
Request BodyCopiar
```
{
"amount": 10000,
"description": "Pedido Marketplace #123",
"postbackUrl": "https://plataforma.com/webhooks/winnerpay",
"splits": [
{
"recipient": "chave_pix_vendedor",
"amount": 9000
},
{
"recipient": "chave_pix_plataforma",
"amount": 1000
}
]
}
```
Response 200Copiar
```
{
"success": true,
"message": "QR Code PIX gerado com sucesso",
"transaction": {
"transaction_id": "TXN_1697123456_SPLIT01",
"type": "receber_pix",
"status": "pending",
"amount": 100.00,
"splits": [
{
"recipient": "chave_pix_vendedor",
"amount_cents": 9000,
"amount": 90.00
},
{
"recipient": "chave_pix_plataforma",
"amount_cents": 1000,
"amount": 10.00
}
]
},
"split_summary": {
"total_amount_cents": 10000,
"recipients_count": 2
},
"pix_copia_e_cola": "PIX_TXN_1697123456_SPLIT01"
}
```
Response 400 — Soma inválidaCopiar
```
{
"statusCode": 400,
"message": "A soma dos splits deve ser exatamente igual ao valor total da transação",
"error": "Bad Request"
}
```
Response 400 — Valor mínimoCopiar
```
{
"statusCode": 400,
"message": "O valor mínimo para split payment é de R$ 3,00",
"error": "Bad Request"
}
```

================================================================================

Download Documentação
Baixe a documentacao da API nos formatos mais usados para compartilhar, arquivar ou integrar em outros sistemas.

Baixar JSONFormato estruturado para integracoes, parsers e automacoes.Baixar TXTFormato simples e leve para leitura rapida e compartilhamento.Baixar HTMLLeve a versao navegavel da documentacao completa em um arquivo unico.Os downloads abaixo sao gerados para facilitar distribuicao da referencia da API em ambientes tecnicos, suporte e integracoes.

================================================================================

[Cash Out — Transferências] Regras de contrato
Regras e limites para transferências PIX.

Regras de contrato
Valor mínimo: R$ 0,01
Taxa: 3% sobre o valor transferido
Saldo deve cobrir valor + taxa
Transferências PIX são irreversíveis — não podem ser estornadas
Processamento: instantâneo após aprovação
Chaves aceitas: CPF, CNPJ, Email, Telefone, Chave Aleatória

================================================================================

[Cash Out — Transferências] Webhook de saque
Notificação enviada quando uma transferência PIX é concluída.

JSON Payload — Transferência concluídaCopiar
```
{
"event": "transaction.completed",
"transaction_id": "TXN_1697123456_XYZ98765",
"status": "completed",
"previous_status": "processing",
"amount": 100.00,
"fee": 3.00,
"type": "cash_out",
"payment_method": "PIX",
"recipient": {
"pix_key": "destinatario@email.com",
"pix_key_type": "email"
},
"completed_at": "2025-03-28T12:15:30.000Z"
}
```

================================================================================

[Cash Out — Transferências] POST Transferência PIX (saque)
Envie PIX para qualquer chave diretamente via API.

POST/api/financial/transferencia-pixCampoTipoObrig.Descrição
amountfloatreqValor em R$ (mín: 0.01)
recipient_keystringreqChave PIX do destinatário
recipient_documentstringoptCPF/CNPJ do destinatário
descriptionstringoptDescrição da transferência
pix_key_typestringoptemail | cpf | cnpj | phone | random
postbackUrlstringoptURL para notificação de status
Request BodyCopiar
```
{
"amount": 100.50,
"recipient_key": "usuario@email.com",
"recipient_document": "12345678900",
"description": "Pagamento de serviços",
"pix_key_type": "email",
"postbackUrl": "https://meu-servidor.com/webhook"
}
```
Response 200Copiar
```
{
"success": true,
"message": "Transferência PIX criada com sucesso",
"transaction": {
"transaction_id": "TXN_1697123456_ABC12345",
"type": "transferencia_pix",
"status": "pending",
"amount": 100.50,
"fee": 3.02,
"total_amount": 103.52,
"recipient_key": "usuario@email.com"
}
}
```
Response 400 — Saldo insuficienteCopiar
```
{
"success": false,
"message": "Saldo insuficiente para realizar a transferência"
}
```

================================================================================

[Vendas & Clientes] GET Listar vendas
Consulte as vendas realizadas com filtro por status.

GET/api/sales/myQueryValoresDescrição
statusall | paid | pending | refundedFiltrar por status
pageintPágina atual
per_pageint (default 10)Itens por página
Response 200Copiar
```
{
"success": true,
"data": {
"current_page": 1,
"data": [{
"transaction_id": "TXN_...",
"payer_name": "João Silva",
"amount": 250.00,
"fee": 8.75,
"fee_percentage": 3.5,
"status": "paid",
"payment_method": "PIX",
"paid_at": "2025-03-28T12:05:00.000Z"
}],
"total": 50,
"per_page": 10,
"last_page": 5
}
}
```

================================================================================

[Vendas & Clientes] GET Stats de vendas
Métricas consolidadas das vendas pagas.

GET/api/sales/statsResponse 200Copiar
```
{
"success": true,
"data": {
"total_transactions": 150,
"total_processed": 37500.50,
"total_fees": 1312.52,
"average_ticket": 250.00
}
}
```

================================================================================

[Vendas & Clientes] GET Stats de entradas
Detalhamento de pagamentos confirmados e pendentes.

GET/api/sales/entries-statsResponse 200Copiar
```
{
"success": true,
"data": {
"confirmed_payments": 145,
"pending_payments": 5,
"total_billing": 37500.50,
"average_ticket": 258.62
}
}
```

================================================================================

[Referência] Status de transações
Todos os status possíveis de uma transação no WinnerPay.

Status padronizados
pendingAguardando pagamentoprocessingEm processamentopaidPago (webhook cash_in)completedCompletadorefusedRecusado / NegadofailedFalhou / RejeitadocancelledCanceladorefundedReembolsadorefund_pendingEstorno em processo

================================================================================

[Referência] Códigos HTTP
Referência dos códigos de resposta da API.

CódigoStatusDescrição
200OKRequisição bem-sucedida
201CreatedRecurso criado com sucesso
400Bad RequestParâmetro obrigatório ausente ou inválido
401UnauthorizedToken inválido ou não fornecido
403ForbiddenSem permissão ou credencial bloqueada
404Not FoundRecurso não encontrado
422UnprocessableDados inválidos na validação
500Server ErrorErro interno no servidor

================================================================================

[Referência] Taxas & Limites
Tabela de taxas operacionais do WinnerPay.

Taxas de operação
OperaçãoTaxaObservação
Transferência PIX (cash-out)3%Sobre o valor enviado
Receber PIX (cash-in)Conforme contratoDefinido na aprovação KYC

================================================================================