Skip to main content

​
Base URL

Todas as requisições da API devem ser feitas para: 
https://api.stylepay.com.br

​
Autenticação

Todas as requisições requerem autenticação via headers customizados: 
stpi: seu_client_id
stps: seu_client_secret

Como autenticar

Veja o guia completo de autenticação

​
Endpoints Disponíveis

​
💰 Gateway PIX

Endpoints para criar e gerenciar cobranças e pagamentos PIX.

Gerar QR Code PIX

POST /api/v1/gateway/request-qrcodeCria uma cobrança PIX e gera o QR Code para pagamento

Realizar Pagamento PIX

POST /api/v1/gateway/pix-paymentEnvia um pagamento PIX para qualquer chave

​
💼 Wallet (Carteira)

Endpoints para gerenciamento de saldo e transações.

Consultar Saldo

GET /api/v1/wallet/balanceConsulta o saldo disponível na carteira

Histórico de Transações

GET /api/v1/wallet/transactionsLista todas as transações realizadas

​
🔔 Webhooks

Sistema de notificações em tempo real.

Webhooks

Configure URLs para receber notificações automáticas sobre mudanças de status em transações

​
Estrutura de Resposta

​
Respostas de Sucesso

Todas as respostas bem-sucedidas retornam status HTTP 2xx: 
{
  "payment_id": "550e8400-e29b-41d4-a716-446655440000",
  "qrcode": "00020126580014br.gov.bcb.pix...",
  "status": "PENDING"
}

​
Respostas de Erro

Erros retornam status HTTP 4xx ou 5xx com a seguinte estrutura: 
{
  "statusCode": 400,
  "message": "Invalid request parameters",
  "error": "Bad Request"
}

​
Códigos de Status Comuns

​
200
OK
Requisição processada com sucesso
​
201
Created
Recurso criado com sucesso
​
400
Bad Request
Parâmetros inválidos na requisição
​
401
Unauthorized
Credenciais de autenticação inválidas ou ausentes
​
404
Not Found
Recurso não encontrado
​
500
Internal Server Error
Erro interno do servidor

​
Rate Limiting

A API StylePay implementa rate limiting para garantir estabilidade:
Limite padrão: 100 requisições por minuto por Client ID
Quando o limite é excedido, você receberá uma resposta 429 Too Many Requests: 
{
  "statusCode": 429,
  "message": "Rate limit exceeded",
  "error": "Too Many Requests",
  "retryAfter": 60
}

​
Headers de Rate Limit

Todas as respostas incluem headers informativos: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

​
Tipos de Dados

​
Valores Monetários

Todos os valores monetários são enviados e recebidos como números decimais em reais (BRL): 
{
  "amount": 100.50,  // R$ 100,50
  "tax": 1.50        // R$ 1,50
}
Sempre use ponto (.) como separador decimal, nunca vírgula (,)

​
Datas

Todas as datas seguem o formato ISO 8601 com timezone UTC: 
{
  "date": "2025-01-01T10:00:00.000Z"
}

​
Documentos

CPF e CNPJ devem ser enviados apenas com números, sem pontos, traços ou barras: 
{
  "document": "12345678900"     // CPF
}

{
  "document": "12345678000100"  // CNPJ
}

​
Chaves PIX

Tipos de chave PIX aceitos:
TipoFormatoExemplo
CPF11 dígitos12345678900
CNPJ14 dígitos12345678000100
EMAILEmail válidousuario@email.com
PHONE+55 + DDD + número+5511999999999
EVPUUID v4550e8400-e29b-41d4-a716-446655440000

​
Idempotência

Para operações críticas como criação de pagamentos, use o campo external_id para garantir idempotência: 
{
  "amount": 100.50,
  "external_id": "pedido_123_tentativa_1"
}
Se você enviar a mesma requisição com o mesmo external_id múltiplas vezes, apenas uma transação será criada.

​
Ambientes

​
Produção

https://api.stylepay.com.br
Este é o ambiente de produção. Todas as transações movimentam dinheiro real.

​
Bibliotecas e SDKs

Estamos trabalhando em SDKs oficiais. Por enquanto, você pode integrar usando bibliotecas HTTP padrão: 
// Usando fetch nativo
const response = await fetch('https://api.stylepay.com.br/api/v1/endpoint', {
  method: 'POST',
  headers: {
    'stpi': process.env.STYLEPAY_CLIENT_ID,
    'stps': process.env.STYLEPAY_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
});

​
Webhooks

A API StylePay envia notificações automáticas para sua aplicação quando eventos importantes ocorrem:

Cash-in

Notificações de recebimentos

Cash-out

Notificações de pagamentos

Refunds

Notificações de estornos

Configurar Webhooks

Veja como configurar e processar webhooks

​
Exemplos Práticos

​
Fluxo Completo: Receber Pagamento

1

Criar QR Code

POST /api/v1/gateway/request-qrcode
Gera QR Code para o cliente pagar
2

Cliente Paga

O cliente escaneia o QR Code e confirma o pagamento no app do banco
3

Receber Webhook

{
  "event": "pix.cashin.paid",
  "statusTransaction": "PAID",
  "value": 100.50
}
Você recebe notificação automática do pagamento
4

Confirmar Saldo

GET /api/v1/wallet/balance
Consulta o saldo atualizado na carteira

​
Fluxo Completo: Enviar Pagamento

1

Verificar Saldo

GET /api/v1/wallet/balance
Confirma que tem saldo suficiente
2

Enviar Pagamento

POST /api/v1/gateway/pix-payment
Envia PIX para a chave do destinatário
3

Receber Confirmação

{
  "event": "pix.cashout.paid",
  "statusTransaction": "PAID"
}
Webhook confirma que pagamento foi realizado

​
Suporte

Documentação

Guias e tutoriais completos

WhatsApp

+55 11 9999-9999

​
Próximos Passos

Gerar QR Code PIX

Comece criando sua primeira cobrança

Realizar Pagamento

Aprenda a enviar pagamentos PIX

Consultar Saldo

Gerencie o saldo da sua carteira

Configurar Webhooks

Receba notificações em tempo real