Bem-vindo à WinnerPay

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

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ção

Saiba como gerar suas chaves de API e autenticar requisições com segurança.

Webhooks

Entenda como receber notificações em tempo real sobre eventos da sua conta.

Gere sua primeira venda

Crie um QR Code PIX e receba pagamentos imediatamente via API.

Solicite um saque

Transfira saldo para qualquer chave PIX diretamente via API.

Configure split payment

Crie cobranças PIX com divisão entre vendedor, plataforma e gateway.

Base URL

URL

https://api.winnerpayy.com.br/api

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 Header

Authorization: Basic {base64(client_id:client_secret)}

Opção 2 — Headers separados

HTTP Headers

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 Header

Authorization: Bearer seu_jwt_token

Registrar usuário

POST /api/auth/register

Campo	Tipo	Obrig.	Descrição
`name`	string	req	Nome completo
`email`	string	req	E-mail único
`password`	string	req	Mínimo 8 caracteres
`username`	string	req	Username único
`phone`	string	opt	Telefone
`cnpj`	string	opt	CNPJ da empresa

Response 200

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 1,
    "name": "João Silva",
    "email": "joao@email.com",
    "kyc_status": "pending",
    "is_sandbox": true
  }
}

Login

POST /api/auth/login

Campo	Tipo	Obrig.	Descrição
`email`	string	req	E-mail cadastrado
`password`	string	req	Senha

Response 200

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { /* dados do usuário */ },
  "requires_company": false,
  "is_sandbox": false
}

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ção

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 Payload

{
  "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.created

Transação criada

transaction.status.updated

Status atualizado

transaction.completed

Completada com sucesso

transaction.processing

Em processamento

transaction.refused

Recusada

transaction.failed

Falhou

transaction.refunded

Estornada

transaction.cancelled

Cancelada

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/me

{
  "kyc_status": "pending",  // pending | approved | rejected
  "is_sandbox": true         // false quando aprovado
}

Regras — Cash In

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

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 confirmado

{
  "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"
}

Gerar QR Code PIX

Crie uma cobrança PIX e receba pagamentos instantâneos.

POST /api/financial/receber-pix

Gera 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

Campo	Tipo	Obrig.	Descrição
`amount`	float	opt	Valor em R$ (0 = QR dinâmico)
`description`	string	opt	Descrição do pagamento
`postbackUrl`	string	opt	URL para receber notificações webhook
`metadata`	object	opt	Dados adicionais (ex.: `order_id`, `product: { name }`)
`user_metadata`	object	opt	Mesclado com `metadata` (atalho no body)
`product`	string \| object	opt	Atalho na raiz; string vira `{ name }`
`product_name`	string	opt	Atalho na raiz = nome do produto (painel)
`customer`	object	opt	Dados do pagador (nome, CPF, email, endereço)
`items`	array	opt	Itens da cobrança
`payer`	object	opt	Formato simplificado do pagador
`external_id`	string	opt	ID externo para referência
`payerQuestion`	string	opt	Texto exibido ao pagador (opcional)

Request Body

{
  "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 200

{
  "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"
}

Listar Transações

Consulte o histórico paginado de todas as transações da conta.

GET /api/financial/transactions

Query	Tipo	Default	Descrição
`page`	int	1	Página atual
`per_page`	int	15	Itens por página

Response 200

{
  "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
  }
}

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 200

{
  "success": true,
  "message": "Transação estornada com sucesso",
  "transaction": {
    "transaction_id": "TXN_1697123456_ABC12345",
    "status": "refunded",
    "amount": 100.50
  }
}

Response 400

{
  "success": false,
  "message": "Apenas transações pagas/completas podem ser estornadas"
}

Dados do Seller

Retorna os dados cadastrais da empresa vinculada às credenciais.

GET /api/seller

Response 200

{
  "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 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/split

Cria 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).

Campo	Tipo	Obrig.	Descrição
`amount`	integer	req	Valor total da cobrança em centavos. Mínimo: `300`.
`splits`	array	req	Lista de recebedores e respectivos valores em centavos.
`splits[].recipient`	string	req	Identificador/chave PIX do recebedor.
`splits[].amount`	integer	req	Parcela do recebedor em centavos.
`description`	string	opt	Descrição da cobrança PIX.
`postbackUrl`	string	opt	Webhook para atualização de status da cobrança.

Request Body

{
  "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 200

{
  "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álida

{
  "statusCode": 400,
  "message": "A soma dos splits deve ser exatamente igual ao valor total da transação",
  "error": "Bad Request"
}

Response 400 — Valor mínimo

{
  "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 JSON

Formato estruturado para integracoes, parsers e automacoes.

Baixar TXT

Formato simples e leve para leitura rapida e compartilhamento.

Baixar HTML

Leve 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.

Regras — Cash Out

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

Webhook de Saque

Notificação enviada quando uma transferência PIX é concluída.

JSON Payload — Transferência concluída

{
  "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"
}

Transferência PIX (saque)

Envie PIX para qualquer chave diretamente via API.

POST /api/financial/transferencia-pix

Campo	Tipo	Obrig.	Descrição
`amount`	float	req	Valor em R$ (mín: 0.01)
`recipient_key`	string	req	Chave PIX do destinatário
`recipient_document`	string	opt	CPF/CNPJ do destinatário
`description`	string	opt	Descrição da transferência
`pix_key_type`	string	opt	email \| cpf \| cnpj \| phone \| random
`postbackUrl`	string	opt	URL para notificação de status

Request Body

{
  "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 200

{
  "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 insuficiente

{
  "success": false,
  "message": "Saldo insuficiente para realizar a transferência"
}

Listar Vendas

Consulte as vendas realizadas com filtro por status.

GET /api/sales/my

Query	Valores	Descrição
`status`	all \| paid \| pending \| refunded	Filtrar por status
`page`	int	Página atual
`per_page`	int (default 10)	Itens por página

Response 200

{
  "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
  }
}

Estatísticas de Vendas

Métricas consolidadas das vendas pagas.

GET /api/sales/stats

Response 200

{
  "success": true,
  "data": {
    "total_transactions": 150,
    "total_processed": 37500.50,
    "total_fees": 1312.52,
    "average_ticket": 250.00
  }
}

Estatísticas de Entradas

Detalhamento de pagamentos confirmados e pendentes.

GET /api/sales/entries-stats

Response 200

{
  "success": true,
  "data": {
    "confirmed_payments": 145,
    "pending_payments": 5,
    "total_billing": 37500.50,
    "average_ticket": 258.62
  }
}

Status de Transações

Todos os status possíveis de uma transação no WinnerPay.

Status padronizados

pending

Aguardando pagamento

processing

Em processamento

paid

Pago (webhook cash_in)

completed

Completado

refused

Recusado / Negado

failed

Falhou / Rejeitado

cancelled

Cancelado

refunded

Reembolsado

refund_pending

Estorno em processo

Em webhooks de pagamento recebido (cash_in), o status será sempre paid. Em consultas via API, pode aparecer como completed. Ambos representam pagamento confirmado.

Códigos HTTP

Referência dos códigos de resposta da API.

Código	Status	Descrição
200	OK	Requisição bem-sucedida
201	Created	Recurso criado com sucesso
400	Bad Request	Parâmetro obrigatório ausente ou inválido
401	Unauthorized	Token inválido ou não fornecido
403	Forbidden	Sem permissão ou credencial bloqueada
404	Not Found	Recurso não encontrado
422	Unprocessable	Dados inválidos na validação
500	Server Error	Erro interno no servidor

Taxas & Limites

Tabela de taxas operacionais do WinnerPay.

Taxas de operação

Operação	Taxa	Observação
Transferência PIX (cash-out)	3%	Sobre o valor enviado
Receber PIX (cash-in)	Conforme contrato	Definido na aprovação KYC