Documentação da API — FlowinPay
API REST para receber PIX no Brasil. Autenticação por chave no header X-Api-Key. Base: https://app.flowinpay.com.br/api/v1.
Versão legível por IA: llms.txt · documentação completa em Markdown.
- Autenticação — App ID (header X-Api-Key), public_id e permissões.
- Cobranças (PIX) — Criar cobranças PIX, com split de pagamento (% ou fixo).
- Pix Recorrente — Assinaturas com débito automático: autorização única, ciclos cobrados sozinhos.
- Saldo — Consultar saldo disponível, bloqueado e resumo financeiro.
- Saques — Solicitar e listar saques via PIX.
- Transações — Extrato de transações e filtros.
- Webhooks — Eventos, payloads e verificação de assinatura HMAC.
- Guia de Webhooks — Passo a passo para receber webhooks (várias linguagens).
- Taxas — Taxas vigentes (2% + R$ 1) e limites.
- Página de Pagamento — Página pública de pagamento PIX.
- Erros — Códigos de erro e tratamento.
- Ambiente de testes — sandbox.flowinpay.com.br: homologar cobrança, split, saque e webhooks sem dinheiro real.
Autenticação
Autenticação
A API FlowinPay utiliza uma App ID (API Key) para autenticação. Todas as requisições à API REST (/api/v1/...) devem incluir o header X-Api-Key.
Gerar a App ID
- Acesse o painel em
https://app.flowinpay.com.br/api-keys
- Clique em Nova chave
- Defina um nome e as permissões desejadas
- Copie a App ID gerada (formato:
fpk_xxxxxxxxxxxxxxxx)
Atenção: A App ID completa só é exibida uma vez. Guarde em local seguro.
Como Usar
Inclua a App ID no header X-Api-Key em todas as requisições:
X-Api-Key: fpk_xxxxxxxxxxxxxxxx
Exemplo
curl -X GET "https://app.flowinpay.com.br/api/v1/balance" \
-H "X-Api-Key: fpk_xxxxxxxxxxxxxxxx" \
-H "Accept: application/json"
public_id — recebedor de split
Além da App ID (secreta), sua conta tem um public_id: um identificador público usado para te incluir como recebedor em um split de pagamento de outra conta. Fica no painel em Minha Conta → "ID de recebedor (Split)" e pode ser compartilhado sem risco — ele não autentica nada, serve só para receber. Veja Cobranças → Split de Pagamento.
A App ID é como a sua senha (secreta, no header X-Api-Key); o public_id é como o número da conta para receber split (público). São coisas diferentes.
Permissões
A App ID pode ter escopos específicos:
| Permissão |
Descrição |
charge:read |
Consultar cobranças |
charge:create |
Criar cobranças |
charge:cancel |
Cancelar cobranças |
withdrawal:read |
Consultar saques |
withdrawal:create |
Solicitar saques |
balance:read |
Consultar saldo, extrato e resumo |
webhook:create |
Criar e remover webhooks via API |
* |
Acesso total |
Restrição por IP
Opcionalmente, a App ID pode ser restrita a uma lista de IPs autorizados. Requisições de outros IPs recebem 403.
Autenticação do Painel (login)
O painel administrativo usa um Bearer Token gerado no login — diferente da App ID da API:
curl -X POST "https://app.flowinpay.com.br/api/login" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"email":"usuario@email.com","password":"senha123"}'
Response:
{
"user": {
"id": 1,
"name": "João Silva",
"email": "usuario@email.com"
},
"token": "1|abc123def456..."
}
Use o token retornado no header Authorization: Bearer 1|abc123def456... — apenas para as rotas do painel. As rotas /api/v1/* continuam usando X-Api-Key.
Erros de Autenticação
| Status |
Descrição |
401 |
App ID ausente, inválida ou revogada |
403 |
App ID válida, mas sem permissão para o recurso (ou IP não autorizado) |
429 |
Rate limit excedido |
Cobranças (PIX)
Cobranças (PIX)
Criar Cobrança
Permite requisição de pagamento PIX. Após o processamento, webhooks serão enviados para a callbackUrl fornecida.
POST /api/v1/charges
Headers
| Header |
Valor |
X-Api-Key |
fpk_xxxx |
Content-Type |
application/json |
Accept |
application/json |
Body
| Campo |
Tipo |
Obrigatório |
Descrição |
value |
number |
Sim |
Valor em reais (mín: R$2, máx: R$150) |
description |
string |
Não |
Descrição da cobrança |
callbackUrl |
string |
Não |
URL para receber webhooks (cria webhook automaticamente) |
webhook_url |
string |
Não |
Alias para callbackUrl |
customer_name |
string |
Não |
Nome do pagador |
customer_email |
string |
Não |
Email do pagador |
customer_tax_id |
string |
Não |
CPF/CNPJ do pagador |
customer_phone |
string |
Não |
Telefone do pagador |
split |
array |
Não |
Divisão do pagamento entre até 3 recebedores (ver seção Split de Pagamento) |
Exemplo
curl -X POST "https://app.flowinpay.com.br/api/v1/charges" \
-H "X-Api-Key: fpk_xxxx" \
-H "Content-Type: application/json" \
-d '{
"value": 50.00,
"description": "Pedido #123",
"callbackUrl": "https://seusite.com/webhook/flowinpay",
"customer_name": "João Silva",
"customer_email": "joao@email.com"
}'
Response (200)
{
"message": "Cashin request successfully submitted",
"charge": {
"id": 42,
"correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"value": "50.00",
"fee_value": "2.00",
"status": "active",
"br_code": "00020101021226580014br.gov.bcb.pix...",
"qr_code_image": "https://app.flowinpay.com.br/storage/qr/abc123.png",
"payment_link_url": "https://app.flowinpay.com.br/pay/a1b2c3d4...",
"expires_at": "2026-06-06T13:00:00Z"
}
}
Campos Importantes
| Campo |
Descrição |
br_code |
PIX copia e cola — exiba para o pagador |
payment_link_url |
Link de pagamento — compartilhe com o pagador |
qr_code_image |
URL da imagem do QR Code |
expires_at |
Expiração (geralmente 24h) |
Split de Pagamento (opcional)
Divida o valor de uma cobrança entre até 3 contas FlowinPay, identificadas pelo public_id de cada recebedor (disponível no painel em Minha Conta → "ID de recebedor (Split)").
Campo split
Array de objetos, cada um com:
| Campo |
Tipo |
Descrição |
type |
string |
percentage (porcentagem, 1 a 99) ou fixed (valor fixo em R$) |
value |
number |
A porcentagem (se percentage) ou o valor em reais (se fixed) |
recipient |
string |
O public_id da conta que vai receber |
Regras
- A taxa da FlowinPay (R$ 1 + 2%) é descontada primeiro, sobre o valor cheio.
percentage incide sobre o valor cheio da cobrança; fixed é um valor absoluto.
- O dono da cobrança (você) fica com o restante.
- A soma (taxa + splits) não pode ultrapassar o valor da cobrança.
Exemplo
curl -X POST "https://app.flowinpay.com.br/api/v1/charges" \
-H "X-Api-Key: fpk_xxxx" \
-H "Content-Type: application/json" \
-d '{
"value": 100,
"split": [
{ "type": "percentage", "value": 10, "recipient": "PUBLIC_ID_A" },
{ "type": "fixed", "value": 20, "recipient": "PUBLIC_ID_B" }
]
}'
Para uma cobrança de R$ 100: taxa R$ 3,00 · Recebedor A 10% = R$ 10,00 · Recebedor B fixo = R$ 20,00 · você fica com R$ 67,00. O crédito cai direto no saldo de cada recebedor quando o pagamento é confirmado.
Listar Cobranças
GET /api/v1/charges
Query Parameters
| Parâmetro |
Tipo |
Descrição |
status |
string |
Filtrar por status |
page |
integer |
Página (padrão: 1) |
Response (200)
{
"current_page": 1,
"data": [
{
"id": 42,
"correlation_id": "a1b2c3d4...",
"value": "50.00",
"status": "paid",
"description": "Pedido #123",
"paid_at": "2026-06-05T14:30:00Z",
"created_at": "2026-06-05T13:00:00Z"
}
],
"last_page": 1,
"total": 1
}
Consultar Cobrança
GET /api/v1/charges/{id}
Response (200)
{
"charge": {
"id": 42,
"correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"value": "50.00",
"fee_value": "2.00",
"fee_percent": "2.00",
"status": "paid",
"br_code": "00020101021226580014br.gov.bcb.pix...",
"payment_link_url": "https://app.flowinpay.com.br/pay/a1b2c3d4...",
"description": "Pedido #123",
"customer_name": "João Silva",
"paid_at": "2026-06-05T14:30:00Z",
"expires_at": "2026-06-06T13:00:00Z",
"created_at": "2026-06-05T13:00:00Z"
}
}
Cancelar Cobrança
POST /api/v1/charges/{id}/cancel
Response (200)
{
"message": "Cobrança cancelada com sucesso",
"charge": {
"id": 42,
"status": "cancelled"
}
}
Apenas cobranças com status active podem ser canceladas.
Status das Cobranças
| Status |
Descrição |
pending |
Aguardando processamento |
active |
PIX gerado, aguardando pagamento |
paid |
Pagamento confirmado |
cancelled |
Cancelada pelo usuário |
expired |
Expirada (após 24h) |
Fluxo de Pagamento
- Crie a cobrança → Receba
br_code e payment_link_url
- Envie o link → Compartilhe
payment_link_url com o pagador
- Aguarde confirmação → Use webhooks para receber notificação
- Consulte se necessário → Use
GET /api/v1/charges/{id}
Webhook Automático (callbackUrl)
Ao criar uma cobrança, passe callbackUrl no body — a FlowinPay criará automaticamente um webhook na sua conta apontando para essa URL. Quando o pagamento for confirmado (ou expirar/cancelar), enviaremos um POST para a URL.
Importante: Se a mesma callbackUrl for usada em múltiplas cobranças, apenas um webhook será criado (sem duplicatas). O webhook aparece no painel em Desenvolvedor → API Keys → aba Webhooks.
Guarde o secret: na cobrança que criou o webhook, a resposta traz o campo webhook_secret (whsec_...) uma única vez. Ele é a chave para validar o header X-FlowinPay-Signature. Se perder, regenere no painel. Detalhes em Webhooks.
Pix Recorrente
Pix Recorrente (assinaturas)
Assinatura com débito automático. O cliente autoriza uma vez no app do banco dele e os
ciclos seguintes são liquidados sozinhos, sem ele pagar nada de novo.
É diferente de uma cobrança comum: em /charges você gera um PIX e o cliente paga cada um.
Aqui ele autoriza a recorrência e você deixa de depender da ação dele todo mês.
Antes de começar
CPF (ou CNPJ) e nome do cliente são obrigatórios. Não é exigência da FlowinPay: o Banco
Central pede identificação do pagador para autorizar um débito recorrente. Se o seu checkout
hoje não coleta CPF, precisa passar a coletar antes de usar assinatura.
Como funciona
| Passo |
Quem faz |
O que acontece |
| 1 |
Você |
Cria a assinatura e recebe um QR Code de autorização |
| 2 |
Seu cliente |
Lê o QR no app do banco e autoriza a recorrência |
| 3 |
FlowinPay |
Avisa em subscription.authorized — libere o acesso |
| 4 |
FlowinPay |
A cada ciclo, cobra sozinha e avisa em subscription.charged |
Endpoints
| Método |
Rota |
Descrição |
| POST |
/api/v1/subscriptions |
Criar assinatura |
| GET |
/api/v1/subscriptions |
Listar |
| GET |
/api/v1/subscriptions/{id} |
Consultar |
| GET |
/api/v1/subscriptions/{id}/charges |
Ciclos da assinatura |
| DELETE |
/api/v1/subscriptions/{id} |
Cancelar |
Criar assinatura
| Campo |
Tipo |
Obrigatório |
Descrição |
value |
number |
sim |
Valor de cada ciclo, em reais |
interval |
string |
sim |
weekly, monthly, quarterly, semiannual ou annual |
description |
string |
sim |
Até 35 caracteres — é o texto que o cliente vê no app do banco |
customer_name |
string |
sim |
Nome do cliente |
customer_tax_id |
string |
sim |
CPF (11 dígitos) ou CNPJ (14) |
start_date |
string |
não |
Data do primeiro ciclo (YYYY-MM-DD). Precisa ser posterior a hoje — o Banco Central recusa cobrança que vence no mesmo dia em que é criada. Padrão: amanhã |
end_date |
string |
não |
Encerra nesta data. Sem ela, prazo indeterminado |
webhook_url |
string |
não |
URL de callback, igual às cobranças |
O description é a única coisa que o cliente lê na hora de autorizar. Use o nome do produto:
"Clube VIP · mensal" funciona; "assinatura" não diz nada e derruba conversão.
O primeiro ciclo é sempre cobrado junto com a autorização: o QR é composto, e o cliente
paga e autoriza no mesmo gesto. Não há parâmetro para separar as duas coisas.
curl -X POST "https://app.flowinpay.com.br/api/v1/subscriptions" \
-H "X-Api-Key: fpk_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"value":29.90,"interval":"monthly","description":"Clube VIP · mensal",
"customer_name":"Maria Souza","customer_tax_id":"12345678909"}'
{
"subscription": {
"id": 17,
"status": "criada",
"valor": "29.90",
"periodicidade": "monthly",
"objeto": "Clube VIP · mensal",
"pagador_nome": "Maria Souza",
"data_inicio": "2026-09-21",
"proximo_ciclo_em": "2026-10-21",
"ciclos_gerados": 1,
"codigo_autorizacao": "00020126870014br.gov.bcb.pix2565pix..."
}
}
O codigo_autorizacao é o Pix copia e cola. Gere o QR a partir dele, ou mande o texto — o
cliente aponta a câmera do banco ou cola, e o banco pede que ele pague o primeiro ciclo e
autorize os seguintes no mesmo gesto.
O documento do pagador (pagador_documento) não volta na resposta: é CPF de terceiro, e não
sai da plataforma.
Enquanto ele não autorizar, a assinatura fica em criada e nada é cobrado. Se o
codigo_autorizacao vier nulo, consulte a assinatura de novo em alguns segundos — o
GET /subscriptions/{id} busca o código na instituição de pagamento quando ele falta.
Status da assinatura
Os valores são estes, em português, exatamente como aparecem no campo status:
| Status |
Significado |
criada |
Esperando o cliente autorizar no banco |
aprovada |
Autorizada — os ciclos são cobrados sozinhos |
rejeitada |
O cliente recusou a autorização |
expirada |
O prazo de autorização passou sem resposta |
cancelada |
Cancelada por você, pelo cliente ou pelo banco dele |
falhou |
A tentativa não chegou à instituição de pagamento; ninguém foi convidado a autorizar |
O cliente pode cancelar a qualquer momento pelo app do banco, sem passar por você. Quando isso
acontece você recebe subscription.canceled — é o sinal para cortar o acesso.
Quando um ciclo falha
Saldo insuficiente não cancela a assinatura. A FlowinPay tenta de novo sozinha — até 3 vezes
em 7 dias a partir do vencimento. Você só recebe subscription.payment_failed depois que
todas as tentativas falharem.
Webhooks
| Evento |
Quando |
O que fazer |
subscription.authorized |
Cliente autorizou |
Liberar o acesso |
subscription.charged |
Ciclo liquidado |
Manter o acesso |
subscription.payment_failed |
Ciclo falhou após as retentativas |
Suspender o acesso |
subscription.canceled |
Assinatura encerrada |
Revogar o acesso |
Os ciclos aparecem no extrato normal
Cada ciclo pago é uma cobrança como qualquer outra: credita saldo, desconta taxa e aparece em
/api/v1/charges e /api/v1/transactions, com o campo subscription_id preenchido.
Quem já concilia por ali não precisa mudar nada — e quem quiser separar assinatura de venda
avulsa é só filtrar por esse campo.
Saldo
Saldo e Resumo Financeiro
Consultar Saldo
GET /api/v1/balance
Response (200)
{
"balance": {
"available": 1250.75,
"blocked": 100.00,
"total": 1350.75
}
}
Campos
| Campo |
Tipo |
Descrição |
available |
number |
Saldo disponível para saque |
blocked |
number |
Saldo bloqueado (saques pendentes) |
total |
number |
Total (available + blocked) |
Exemplo
curl -X GET "https://app.flowinpay.com.br/api/v1/balance" \
-H "X-Api-Key: fpk_xxxx" \
-H "Accept: application/json"
Resumo Financeiro
GET /api/v1/summary
Response (200)
{
"summary": {
"today": {
"income": 1500.00,
"expenses": 200.00,
"fees": 45.00,
"count": 12
},
"week": {
"income": 8500.00,
"expenses": 1200.00,
"fees": 210.00,
"count": 65
},
"month": {
"income": 32000.00,
"expenses": 5000.00,
"fees": 850.00,
"count": 240
},
"counts": {
"charges": 240,
"withdrawals": 5,
"disputes": 2
}
}
}
Exemplo
curl -X GET "https://app.flowinpay.com.br/api/v1/summary" \
-H "X-Api-Key: fpk_xxxx" \
-H "Accept: application/json"
Saques
Saques (CashOut)
Endpoints para solicitar e consultar saques via PIX.
Solicitar Saque
POST /api/v1/withdrawals
Body
| Campo |
Tipo |
Obrigatório |
Descrição |
value |
number |
Sim |
Valor em reais (mín: R$10) |
pix_key |
string |
Sim |
Chave PIX de destino |
pix_key_type |
string |
Sim |
Tipo: cpf, cnpj, email, phone, random |
description |
string |
Não |
Descrição do saque |
Exemplo
curl -X POST "https://app.flowinpay.com.br/api/v1/withdrawals" \
-H "X-Api-Key: fpk_xxxx" \
-H "Content-Type: application/json" \
-d '{
"value": 100.00,
"pix_key": "12345678901",
"pix_key_type": "cpf",
"description": "Saque mensal"
}'
Response (201)
{
"message": "Saque solicitado com sucesso",
"withdrawal": {
"id": 15,
"value": "100.00",
"fee_value": "2.00",
"net_value": "98.00",
"pix_key": "12345678901",
"pix_key_type": "cpf",
"status": "pending",
"description": "Saque mensal",
"created_at": "2026-06-05T15:00:00.000000Z"
}
}
Taxas
| Configuração |
Valor |
| Taxa fixa |
R$2,00 por saque |
| Valor mínimo |
R$10,00 |
| Processamento |
Até 1 hora útil |
Listar Saques
GET /api/v1/withdrawals
Response (200)
[
{
"id": 15,
"value": "100.00",
"fee_value": "2.00",
"net_value": "98.00",
"pix_key": "12345678901",
"pix_key_type": "cpf",
"status": "completed",
"processed_at": "2026-06-05T15:30:00.000000Z",
"created_at": "2026-06-05T15:00:00.000000Z"
}
]
Status dos Saques
| Status |
Descrição |
pending |
Aguardando processamento |
processing |
Em processamento na adquirente |
completed |
Saque concluído |
failed |
Falha no processamento |
cancelled |
Cancelado pelo usuário |
Erros Comuns
| Status |
Erro |
Solução |
| 422 |
Saldo insuficiente |
Verifique o saldo antes de solicitar |
| 422 |
Valor mínimo R$10 |
Aumente o valor do saque |
| 422 |
Chave PIX inválida |
Verifique o tipo e formato da chave |
| 429 |
Rate limit (60/min) |
Aguarde antes de tentar novamente |
Transações
Transações (Extrato)
Listar Transações
GET /api/v1/transactions
Query Parameters
| Parâmetro |
Tipo |
Descrição |
type |
string |
Filtrar por tipo: charge_received, split_received, charge_fee, withdrawal, withdrawal_fee, refund, adjustment |
start_date |
date |
Data inicial (YYYY-MM-DD) |
end_date |
date |
Data final (YYYY-MM-DD) |
min_amount |
number |
Valor mínimo |
max_amount |
number |
Valor máximo |
search |
string |
Buscar por descrição |
page |
integer |
Página |
Response (200)
{
"current_page": 1,
"data": [
{
"id": 150,
"type": "charge_received",
"amount": "48.00",
"balance_before": "1000.00",
"balance_after": "1048.00",
"description": "Pagamento cobrança #42",
"reference_type": "App\\Models\\Charge",
"reference_id": 42,
"created_at": "2026-06-05T14:30:00.000000Z"
}
],
"last_page": 1,
"total": 1
}
Tipos de Transação
| Tipo |
Descrição |
Sinal |
charge_received |
Recebimento de cobrança |
+ |
split_received |
Recebimento via split |
+ |
charge_fee |
Taxa da cobrança |
- |
withdrawal |
Saque |
- |
withdrawal_fee |
Taxa do saque |
- |
refund |
Estorno |
+ |
adjustment |
Ajuste manual |
+/- |
Exemplo
curl -X GET "https://app.flowinpay.com.br/api/v1/transactions?type=charge_received&start_date=2026-06-01" \
-H "X-Api-Key: fpk_xxxx" \
-H "Accept: application/json"
Consultar Transação
GET /api/v1/transactions/{id}
Response (200)
{
"transaction": {
"id": 150,
"type": "charge_received",
"amount": "48.00",
"balance_before": "1000.00",
"balance_after": "1048.00",
"description": "Pagamento cobrança #42",
"reference_type": "App\\Models\\Charge",
"reference_id": 42,
"created_at": "2026-06-05T14:30:00.000000Z"
}
}
Exemplo
curl -X GET "https://app.flowinpay.com.br/api/v1/transactions/150" \
-H "X-Api-Key: fpk_xxxx" \
-H "Accept: application/json"
Webhooks
Webhooks
Webhooks permitem que seu sistema receba notificações em tempo real sobre eventos na FlowinPay.
Cada entrega tem timeout de 10 segundos. Verifique a assinatura, grave o evento e só então responda HTTP 2xx; o que for demorado (e-mail, entrega do produto), faça depois a partir do que você gravou. O passo a passo, com código em várias linguagens, está no guia de webhooks.
Registrar Webhook
POST /api/v1/webhooks
Body
| Campo |
Tipo |
Obrigatório |
Descrição |
url |
string |
Sim |
URL de destino, HTTPS |
events |
array |
Sim |
Eventos desejados |
description |
string |
Não |
Descrição do webhook |
Eventos Disponíveis
| Evento |
Descrição |
charge.created |
Cobrança criada |
charge.completed |
Cobrança paga |
charge.expired |
Cobrança expirada |
charge.cancelled |
Cobrança cancelada |
charge.refunded |
Cobrança estornada |
withdrawal.completed |
Saque processado |
withdrawal.failed |
Saque falhou |
dispute.opened |
Contestação aberta |
dispute.accepted |
Contestação aceita |
dispute.rejected |
Contestação rejeitada |
dispute.cancelled |
Contestação cancelada |
Exemplo
curl -X POST "https://app.flowinpay.com.br/api/v1/webhooks" \
-H "X-Api-Key: fpk_xxxx" \
-H "Content-Type: application/json" \
-d '{
"url": "https://seusite.com/webhook/flowinpay",
"events": ["charge.completed", "charge.expired"]
}'
Response (201)
{
"message": "Webhook criado com sucesso! Guarde o secret — não será exibido novamente.",
"webhook": {
"id": 1,
"url": "https://seusite.com/webhook/flowinpay",
"events": ["charge.completed", "charge.expired"],
"is_active": true,
"secret": "whsec_xxxxxxxxxxxxxxxxxxxx",
"created_at": "2026-06-05T15:00:00Z"
}
}
Importante: O secret é usado para verificar a assinatura dos webhooks. Guarde-o — não será exibido novamente.
Listar Webhooks
GET /api/v1/webhooks
Response (200)
[
{
"id": 1,
"url": "https://seusite.com/webhook/flowinpay",
"events": ["charge.completed", "charge.expired"],
"is_active": true,
"secret_preview": "whsec_xxxxx••••••••",
"last_triggered_at": "2026-06-05T16:00:00Z",
"failure_count": 0,
"created_at": "2026-06-05T15:00:00Z"
}
]
Atualizar Webhook
Disponível apenas no painel (autenticação Bearer Token). Não disponível via API Key.
Remover Webhook
DELETE /api/v1/webhooks/{id}
Response (200)
{ "message": "Webhook removido" }
Regenerar Secret
Disponível apenas no painel (autenticação Bearer Token). Não disponível via API Key.
Testar Webhook
Disponível apenas no painel (Desenvolvedor → API Keys → aba Webhooks → Testar). Não disponível via API Key.
O teste envia um POST igual a uma entrega real — mesmos headers, assinado com o mesmo secret — com o evento webhook.test:
{
"event": "webhook.test",
"event_id": "3f2b8c1e-0000-4000-8000-000000000000",
"timestamp": "2026-10-16T00:24:12+00:00"
}
O webhook.test não tem o objeto charge nem outro dado de negócio. Valide a assinatura e responda HTTP 2xx; não rejeite o teste por ser um evento que você não processa. Se o teste mostrar 401/403, o seu endpoint recusou a requisição — quase sempre o secret usado no seu código não é o cadastrado neste webhook, ou a assinatura está sendo calculada sobre o JSON re-serializado em vez do corpo bruto (veja Verificar Assinatura).
O teste não conta como falha do webhook nem o desativa.
Payload do Webhook
Quando um evento ocorre, a FlowinPay envia um POST para sua URL:
Headers
| Header |
Descrição |
Content-Type |
application/json |
X-FlowinPay-Event |
Tipo do evento (ex: charge.completed) — o mesmo valor do campo event do corpo |
X-FlowinPay-Signature |
Assinatura HMAC-SHA256 do corpo bruto, em hexadecimal minúsculo (64 caracteres, sem prefixo) |
X-FlowinPay-Delivery |
Id da entrega — igual ao event_id do corpo. É o mesmo nas re-tentativas: use para não processar o mesmo evento duas vezes |
Todo corpo traz event, event_id e timestamp, além do objeto do evento.
Payload — charge.created / charge.completed / charge.expired / charge.cancelled
{
"event": "charge.completed",
"event_id": "9b1c2d3e-4f50-4a6b-8c7d-0e1f2a3b4c5d",
"charge": {
"id": 42,
"correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"value": 50.00,
"fee_value": 2.00,
"net_value": 48.00,
"status": "paid",
"description": "Pedido #123",
"paid_at": "2026-06-05T14:30:00Z",
"created_at": "2026-06-05T13:00:00Z"
},
"timestamp": "2026-06-05T14:30:00Z"
}
Payload — withdrawal.completed
{
"event": "withdrawal.completed",
"withdrawal": {
"id": 15,
"value": "100.00",
"fee_value": "2.00",
"net_value": "98.00",
"pix_key": "12345678901",
"pix_key_type": "cpf",
"status": "completed",
"processed_at": "2026-06-05T15:30:00Z",
"created_at": "2026-06-05T15:00:00Z"
},
"timestamp": "2026-06-05T15:30:00Z"
}
Payload — withdrawal.failed
{
"event": "withdrawal.failed",
"withdrawal": {
"id": 15,
"value": "100.00",
"fee_value": "2.00",
"net_value": "98.00",
"pix_key": "12345678901",
"pix_key_type": "cpf",
"status": "failed",
"description": "Chave PIX inválida",
"created_at": "2026-06-05T15:00:00Z"
},
"timestamp": "2026-06-05T15:05:00Z"
}
Payload — dispute.opened / dispute.accepted / dispute.rejected / dispute.cancelled
{
"event": "dispute.opened",
"dispute": {
"id": 3,
"charge_id": 42,
"external_id": "dsp_woovi_abc123",
"type": "chargeback",
"status": "open",
"amount": "50.00",
"reason": "Cliente não reconheceu a compra",
"due_at": "2026-06-20T00:00:00Z",
"created_at": "2026-06-10T10:00:00Z"
},
"timestamp": "2026-06-10T10:00:00Z"
}
Response esperada
Retorne HTTP 2xx (por exemplo 200 com {}) depois de gravar o evento. O corpo da resposta é ignorado. Se não conseguir gravar, responda 5xx: a FlowinPay reenvia (veja Retry).
Processar com segurança
- Assinatura sempre. Sem ela, quem descobrir a URL "confirma" pagamentos que não existiram. Assinatura errada → 401, sem tocar no pedido.
- Um evento, uma vez. Guarde o
event_id numa coluna com chave única e ignore o que já foi visto — ele se repete nos reenvios.
- Sem regredir status.
charge.completed só marca pago o pedido que ainda está pendente; charge.expired/charge.cancelled só cancelam o que ainda não foi pago; charge.refunded só estorna o que estava pago.
- Confira o valor. O
value do evento tem que ser o total que o seu servidor calculou para o pedido — nunca um preço que veio do navegador do comprador.
Verificar Assinatura
Use o secret do webhook para verificar que o payload é legítimo:
- Algoritmo: HMAC-SHA256, resultado em hexadecimal minúsculo (64 caracteres), sem prefixo como
sha256=.
- Chave: o
secret completo, incluindo o prefixo whsec_.
- Mensagem: o corpo bruto da requisição, exatamente os bytes recebidos.
Use o corpo bruto, nunca o JSON re-serializado. O corpo é gerado com / escapado (\/) e caracteres acentuados como \u00e3. Se o seu código fizer JSON.parse e depois JSON.stringify (ou json_decode/json_encode), o texto muda e a assinatura deixa de bater — às vezes só em eventos reais com URL ou acento, enquanto o teste passa.
Exemplo para conferir o seu código (valores fictícios):
|
|
| Secret |
whsec_exemploFicticio123 |
| Corpo bruto |
{"event":"webhook.test","event_id":"3f2b8c1e-0000-4000-8000-000000000000","timestamp":"2026-10-16T00:24:12+00:00"} |
| Assinatura esperada |
a05a474d5ebb41024d09060e29f531c7ae589fdd386dea27731abb1d06797a99 |
PHP
$secret = 'whsec_xxxxxxxxxxxx';
$signature = $_SERVER['HTTP_X_FLOWINPAY_SIGNATURE'] ?? '';
$payload = file_get_contents('php://input');
$expected = hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Assinatura inválida');
}
// Processar evento
$data = json_decode($payload, true);
Node.js
const crypto = require('crypto');
// express.raw: req.body chega como Buffer com os bytes originais.
// Não use express.json() nesta rota — ele converte o corpo e a assinatura não bate.
app.post('/webhook/flowinpay', express.raw({ type: 'application/json' }), (req, res) => {
const signature = String(req.headers['x-flowinpay-signature'] || '');
const expected = crypto.createHmac('sha256', secret).update(req.body).digest('hex');
// timingSafeEqual lança erro se os tamanhos forem diferentes; compare o tamanho antes.
const ok = signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
if (!ok) {
return res.status(401).send('Invalid');
}
const event = JSON.parse(req.body.toString('utf8'));
if (event.event === 'webhook.test') return res.json({}); // teste do painel
// Processar evento
res.json({});
});
Fetch API (Next.js, Floot, Cloudflare Workers, Deno, Bun)
import crypto from 'node:crypto';
export async function POST(request) {
const raw = await request.text(); // corpo bruto — leia ANTES de qualquer parse
const signature = request.headers.get('x-flowinpay-signature') || '';
const expected = crypto.createHmac('sha256', process.env.FLOWINPAY_WEBHOOK_SECRET).update(raw).digest('hex');
const ok = signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
if (!ok) return new Response('Invalid', { status: 401 });
const event = JSON.parse(raw);
if (event.event === 'webhook.test') return Response.json({}); // teste do painel
// Processar evento
return Response.json({});
}
Retry
Se a entrega falhar por timeout, erro de conexão, HTTP 5xx, 408 ou 429, a FlowinPay reenvia o mesmo evento (mesmo event_id):
| Tentativa |
Quando |
| 1ª |
Imediato |
| 2ª |
10 segundos depois |
| 3ª |
30 segundos depois |
| 4ª |
2 minutos depois |
| 5ª |
5 minutos depois |
Depois da 5ª tentativa, o evento é dado como não entregue.
Recusas (HTTP 4xx, exceto 408 e 429) não são reenviadas — repetir daria a mesma resposta. Elas contam como falha do webhook:
- 10 recusas seguidas em 1 hora: as entregas para a URL ficam pausadas por 30 minutos e você recebe um e-mail.
- 20 recusas seguidas: o webhook é desativado. Reative no painel depois de corrigir.
- Desativado há 30 dias: você recebe um aviso; 7 dias depois, o webhook é removido.
Uma entrega com sucesso zera a contagem.
Webhook Automático via callbackUrl
Ao criar uma cobrança via API com callbackUrl, a FlowinPay cria automaticamente um webhook na sua conta. Não é necessário criar webhook manualmente — basta passar a URL no momento da cobrança.
curl -X POST "https://app.flowinpay.com.br/api/v1/charges" \
-H "X-Api-Key: fpk_xxxx" \
-H "Content-Type: application/json" \
-d '{
"value": 50.00,
"callbackUrl": "https://seusite.com/webhook/flowinpay"
}'
webhook_url funciona igual (é um alias de callbackUrl).
O webhook é criado com os eventos de cobrança (charge.created, charge.completed, charge.expired, charge.cancelled, charge.refunded) e aparece no painel em Desenvolvedor → API Keys → aba Webhooks. Se já existir um webhook para a mesma URL, nada é criado de novo.
O secret vem uma única vez, na resposta da cobrança que criou o webhook:
{
"charge": { "...": "..." },
"fee": { "...": "..." },
"webhook_secret": "whsec_xxxxxxxxxxxxxxxxxxxx",
"webhook_secret_notice": "Guarde este secret — use-o para validar o header X-FlowinPay-Signature (HMAC-SHA256). Não será exibido novamente."
}
Salve esse valor. Nas cobranças seguintes com a mesma URL, webhook_secret não aparece. Se perder o secret, regenere no painel (Desenvolvedor → API Keys → aba Webhooks → Regenerar) e atualize o seu sistema — o secret antigo deixa de valer na hora.
Guia de Webhooks
Guia: Como Receber Webhooks da FlowinPay
Visão Geral
Quando um evento ocorre na FlowinPay (ex: pagamento confirmado), enviamos um POST para a URL que você configurou. Seu endpoint faz, nesta ordem:
- Lê o corpo bruto da requisição
- Verifica a assinatura
X-FlowinPay-Signature — obrigatório: sem isso, qualquer pessoa que descubra a sua URL consegue "confirmar" um pagamento que não existiu. Assinatura errada → HTTP 401
- Descarta repetidos pelo
event_id — o mesmo evento pode chegar mais de uma vez
- Grava o evento (ou já aplica ao pedido) e só depois responde HTTP 2xx. Se der erro, responda 5xx: a FlowinPay reenvia
- Aplica ao pedido sem regredir: um pedido pago nunca volta para "cancelado", e o valor pago tem que ser o do pedido
Cada entrega tem timeout de 10 segundos. Gravar o evento é rápido; o que for demorado (e-mail, liberar curso, gerar nota), faça depois, numa fila, a partir do que você gravou.
Por que não responder 200 antes de gravar? Se o seu código responde 200 e depois falha (banco fora, erro no deploy), a FlowinPay considera o evento entregue e não reenvia — o pedido fica pago aqui e pendente aí. Responder só depois de gravar faz a falha virar um reenvio.
Passo 1: Configurar a URL
Você pode configurar a URL de webhook de duas formas. A URL precisa ser HTTPS.
Opção A: Via Painel
- Acesse Desenvolvedor → API Keys → aba Webhooks
- Clique em Novo Webhook
- Preencha a URL e selecione os eventos
- Copie o secret (
whsec_...) que aparece na tela — ele não é exibido de novo
Opção B: Via API (Automático)
Ao criar uma cobrança, passe webhook_url no body:
curl -X POST "https://app.flowinpay.com.br/api/v1/charges" \
-H "X-Api-Key: fpk_xxxx" \
-H "Content-Type: application/json" \
-d '{
"value": 50.00,
"webhook_url": "https://seusite.com/webhook/flowinpay"
}'
A FlowinPay criará automaticamente um webhook na sua conta. Na primeira vez, a resposta da cobrança traz o campo webhook_secret — salve-o, ele não aparece de novo. Se perder, regenere no painel (Desenvolvedor → API Keys → aba Webhooks → Regenerar).
Passo 2: Preparar o banco
Duas tabelas bastam: a de pedidos que você já tem (com o payment_id = correlation_id da cobrança e o total calculado no seu servidor) e uma de eventos recebidos, com o event_id como chave única — é ela que impede processar o mesmo evento duas vezes:
CREATE TABLE webhook_events (
event_id VARCHAR(64) PRIMARY KEY, -- igual ao header X-FlowinPay-Delivery
event VARCHAR(40) NOT NULL,
payload TEXT NOT NULL, -- corpo bruto, para auditoria
received_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);
E as três atualizações de pedido, todas com condição de status — é o que impede um evento atrasado de desfazer outro:
-- charge.completed: só sai de "pending", e só se o valor pago for o do pedido
UPDATE orders SET status = 'paid', paid_at = NOW()
WHERE payment_id = :correlation_id AND status = 'pending' AND total = :value;
-- charge.expired / charge.cancelled: só cancela o que AINDA NÃO foi pago
UPDATE orders SET status = 'cancelled'
WHERE payment_id = :correlation_id AND status = 'pending';
-- charge.refunded: só estorna o que estava pago
UPDATE orders SET status = 'refunded'
WHERE payment_id = :correlation_id AND status = 'paid';
Se o UPDATE de pagamento não alterar nenhuma linha, não libere nada: ou o pedido já estava pago (evento repetido), ou o valor não bate — nesse caso, registre e investigue.
Passo 3: Criar o Endpoint
Seu endpoint precisa:
- Aceitar POST
- Ler o body bruto (os bytes exatos recebidos) para validar a assinatura, e só depois converter de JSON
- Responder HTTP 2xx em menos de 10 segundos
- Responder 2xx também ao evento
webhook.test, enviado pelo botão Testar do painel (ele não tem o objeto charge)
A assinatura no header X-FlowinPay-Signature é o HMAC-SHA256 do corpo bruto, em hexadecimal minúsculo, usando o secret completo (com o prefixo whsec_) como chave. Não use o JSON re-serializado: o corpo vem com / escapado (\/) e acentos como ã, e qualquer JSON.stringify/json_encode muda o texto.
Os exemplos abaixo seguem todos a mesma ordem. O PHP e o Node mostram o código completo de banco; nos demais, registrarEvento grava na tabela webhook_events e devolve falso se o event_id já existia, e aplicarEvento roda os UPDATE do Passo 2 — os dois dentro da mesma transação.
PHP
<?php
// webhook.php
$secret = getenv('FLOWINPAY_WEBHOOK_SECRET'); // whsec_... completo, com o prefixo
$pdo = new PDO(getenv('DATABASE_DSN'), getenv('DATABASE_USER'), getenv('DATABASE_PASS'),
[PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
// 1. Corpo bruto
$payload = file_get_contents('php://input');
// 2. Assinatura (obrigatória)
$signature = $_SERVER['HTTP_X_FLOWINPAY_SIGNATURE'] ?? '';
if (!hash_equals(hash_hmac('sha256', $payload, $secret), $signature)) {
http_response_code(401);
exit('Assinatura inválida');
}
$data = json_decode($payload, true);
if (($data['event'] ?? '') === 'webhook.test') { // botão "Testar" do painel
http_response_code(200);
exit('{}');
}
try {
$pdo->beginTransaction();
// 3. Repetido? O INSERT falha na chave única e a gente só confirma o recebimento.
$novo = $pdo->prepare('INSERT IGNORE INTO webhook_events (event_id, event, payload) VALUES (?, ?, ?)');
$novo->execute([$data['event_id'], $data['event'], $payload]);
if ($novo->rowCount() === 1) {
// 4/5. Aplica ao pedido sem regredir status
$charge = $data['charge'] ?? [];
switch ($data['event']) {
case 'charge.completed':
$pdo->prepare("UPDATE orders SET status = 'paid', paid_at = NOW()
WHERE payment_id = ? AND status = 'pending' AND total = ?")
->execute([$charge['correlation_id'], $charge['value']]);
// rowCount() === 1 → enfileire a entrega do produto a partir daqui
break;
case 'charge.expired':
case 'charge.cancelled':
$pdo->prepare("UPDATE orders SET status = 'cancelled' WHERE payment_id = ? AND status = 'pending'")
->execute([$charge['correlation_id']]);
break;
case 'charge.refunded':
$pdo->prepare("UPDATE orders SET status = 'refunded' WHERE payment_id = ? AND status = 'paid'")
->execute([$charge['correlation_id']]);
break;
}
}
$pdo->commit();
} catch (Throwable $e) {
$pdo->rollBack();
error_log('Webhook FlowinPay: ' . $e->getMessage());
http_response_code(500); // a FlowinPay reenvia o mesmo evento
exit;
}
// 6. Só agora: gravado com sucesso
http_response_code(200);
header('Content-Type: application/json');
echo '{}';
INSERT IGNORE é do MySQL. No PostgreSQL use INSERT ... ON CONFLICT (event_id) DO NOTHING; no SQLite, INSERT OR IGNORE.
Node.js (Express + PostgreSQL)
const express = require('express');
const crypto = require('crypto');
const { Pool } = require('pg');
const app = express();
const db = new Pool(); // usa as variáveis PG* do ambiente
const SECRET = process.env.FLOWINPAY_WEBHOOK_SECRET; // whsec_... completo
// express.raw: req.body chega como Buffer com os bytes originais
app.post('/webhook/flowinpay', express.raw({ type: 'application/json' }), async (req, res) => {
// 2. Assinatura (obrigatória) — antes de qualquer resposta
const signature = String(req.headers['x-flowinpay-signature'] || '');
const expected = crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
const ok = signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
if (!ok) return res.status(401).send('Assinatura inválida');
const raw = req.body.toString('utf8');
const data = JSON.parse(raw);
if (data.event === 'webhook.test') return res.json({}); // botão "Testar" do painel
const client = await db.connect();
try {
await client.query('BEGIN');
// 3. Repetido?
const novo = await client.query(
'INSERT INTO webhook_events (event_id, event, payload) VALUES ($1, $2, $3) ON CONFLICT (event_id) DO NOTHING',
[data.event_id, data.event, raw]);
if (novo.rowCount === 1) {
const c = data.charge || {};
if (data.event === 'charge.completed') {
const pago = await client.query(
"UPDATE orders SET status = 'paid', paid_at = NOW() WHERE payment_id = $1 AND status = 'pending' AND total = $2",
[c.correlation_id, c.value]);
// pago.rowCount === 1 → enfileire a entrega do produto
} else if (data.event === 'charge.expired' || data.event === 'charge.cancelled') {
await client.query("UPDATE orders SET status = 'cancelled' WHERE payment_id = $1 AND status = 'pending'", [c.correlation_id]);
} else if (data.event === 'charge.refunded') {
await client.query("UPDATE orders SET status = 'refunded' WHERE payment_id = $1 AND status = 'paid'", [c.correlation_id]);
}
}
await client.query('COMMIT');
res.json({}); // 6. só depois de gravar
} catch (err) {
await client.query('ROLLBACK');
console.error('Webhook FlowinPay:', err);
res.status(500).end(); // a FlowinPay reenvia
} finally {
client.release();
}
});
app.listen(3000, () => console.log('Webhook rodando na porta 3000'));
Python (Flask)
import hmac, hashlib, json, os
from flask import Flask, request
app = Flask(__name__)
SECRET = os.environ['FLOWINPAY_WEBHOOK_SECRET'].encode() # whsec_... completo
@app.route('/webhook/flowinpay', methods=['POST'])
def webhook():
payload = request.get_data() # corpo bruto
signature = request.headers.get('X-FlowinPay-Signature', '')
expected = hmac.new(SECRET, payload, hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature, expected):
return 'Assinatura inválida', 401
data = json.loads(payload)
if data.get('event') == 'webhook.test':
return '{}', 200
try:
with db.transaction(): # sua conexão / ORM
if registrar_evento(data['event_id'], data['event'], payload):
aplicar_evento(data) # UPDATEs do Passo 2
except Exception as e:
app.logger.exception('Webhook FlowinPay')
return '', 500 # a FlowinPay reenvia
return '{}', 200
Java (Spring Boot)
@RestController
public class FlowinPayWebhookController {
private final String secret = System.getenv("FLOWINPAY_WEBHOOK_SECRET"); // whsec_... completo
private final WebhookService service; // registrarEvento + aplicarEvento, @Transactional
public FlowinPayWebhookController(WebhookService service) { this.service = service; }
@PostMapping("/webhook/flowinpay")
public ResponseEntity<String> handle(@RequestBody byte[] body, // bytes brutos
@RequestHeader(value = "X-FlowinPay-Signature", required = false) String signature) {
String expected = hmacSha256Hex(body, secret);
if (signature == null || !MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8),
signature.getBytes(StandardCharsets.UTF_8))) {
return ResponseEntity.status(401).body("Assinatura inválida");
}
JSONObject data = new JSONObject(new String(body, StandardCharsets.UTF_8));
if ("webhook.test".equals(data.getString("event"))) {
return ResponseEntity.ok("{}");
}
try {
service.processar(data, body); // grava em webhook_events e aplica ao pedido, numa transação
} catch (Exception e) {
return ResponseEntity.status(500).build(); // a FlowinPay reenvia
}
return ResponseEntity.ok("{}");
}
private static String hmacSha256Hex(byte[] data, String secret) {
try {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
return HexFormat.of().formatHex(mac.doFinal(data));
} catch (Exception e) {
throw new IllegalStateException(e);
}
}
}
Go
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"io"
"log"
"net/http"
"os"
)
var secret = []byte(os.Getenv("FLOWINPAY_WEBHOOK_SECRET")) // whsec_... completo
type Evento struct {
Event string `json:"event"`
EventID string `json:"event_id"`
Charge json.RawMessage `json:"charge"`
}
func webhookHandler(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(r.Body) // corpo bruto
if err != nil {
http.Error(w, "", http.StatusBadRequest)
return
}
mac := hmac.New(sha256.New, secret)
mac.Write(body)
expected := hex.EncodeToString(mac.Sum(nil))
if !hmac.Equal([]byte(r.Header.Get("X-FlowinPay-Signature")), []byte(expected)) {
http.Error(w, "Assinatura inválida", http.StatusUnauthorized)
return
}
var ev Evento
if err := json.Unmarshal(body, &ev); err != nil {
http.Error(w, "", http.StatusBadRequest)
return
}
if ev.Event != "webhook.test" {
// registrarEvento + aplicarEvento numa transação (database/sql: db.BeginTx)
if err := processar(r.Context(), ev, body); err != nil {
log.Println("webhook FlowinPay:", err)
http.Error(w, "", http.StatusInternalServerError) // a FlowinPay reenvia
return
}
}
w.Header().Set("Content-Type", "application/json")
w.Write([]byte("{}"))
}
func main() {
http.HandleFunc("/webhook/flowinpay", webhookHandler)
log.Fatal(http.ListenAndServe(":3000", nil))
}
C# (.NET)
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using Microsoft.AspNetCore.Mvc;
[ApiController]
public class FlowinPayWebhookController : ControllerBase
{
private static readonly byte[] Secret =
Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("FLOWINPAY_WEBHOOK_SECRET")!); // whsec_...
private readonly WebhookService _service; // registrarEvento + aplicarEvento numa transação
public FlowinPayWebhookController(WebhookService service) => _service = service;
[HttpPost("/webhook/flowinpay")]
public async Task<IActionResult> HandleWebhook()
{
using var ms = new MemoryStream();
await Request.Body.CopyToAsync(ms); // bytes brutos
var body = ms.ToArray();
var expected = Convert.ToHexString(HMACSHA256.HashData(Secret, body)).ToLowerInvariant();
var signature = Request.Headers["X-FlowinPay-Signature"].ToString();
if (!CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(signature), Encoding.UTF8.GetBytes(expected)))
return Unauthorized("Assinatura inválida");
using var doc = JsonDocument.Parse(body);
if (doc.RootElement.GetProperty("event").GetString() == "webhook.test")
return Ok(new { });
try
{
await _service.ProcessarAsync(doc.RootElement, body);
}
catch
{
return StatusCode(500); // a FlowinPay reenvia
}
return Ok(new { });
}
}
Ruby (Sinatra)
require 'sinatra'
require 'json'
require 'openssl'
SECRET = ENV.fetch('FLOWINPAY_WEBHOOK_SECRET') # whsec_... completo
post '/webhook/flowinpay' do
payload = request.body.read # corpo bruto
signature = request.env['HTTP_X_FLOWINPAY_SIGNATURE'].to_s
expected = OpenSSL::HMAC.hexdigest('sha256', SECRET, payload)
halt 401, 'Assinatura inválida' unless Rack::Utils.secure_compare(signature, expected)
data = JSON.parse(payload)
halt 200, '{}' if data['event'] == 'webhook.test'
begin
DB.transaction do # Sequel / ActiveRecord
aplicar_evento(data) if registrar_evento(data['event_id'], data['event'], payload)
end
rescue => e
logger.error("Webhook FlowinPay: #{e.message}")
halt 500 # a FlowinPay reenvia
end
content_type :json
'{}'
end
Passo 4: Testar
Teste via Painel
- Vá em Desenvolvedor → API Keys → aba Webhooks
- No webhook, clique em Testar
O teste envia o evento webhook.test (event, event_id e timestamp, sem charge), com os mesmos headers e a mesma assinatura de uma entrega real. Se aparecer 401/403, foi o seu endpoint que recusou: confira se o secret no seu código é o deste webhook e se a assinatura é calculada sobre o corpo bruto.
O teste só existe no painel; não há endpoint de teste na API com X-Api-Key.
Conferir o cálculo da assinatura (valores fictícios)
|
|
| Secret |
whsec_exemploFicticio123 |
| Corpo bruto |
{"event":"webhook.test","event_id":"3f2b8c1e-0000-4000-8000-000000000000","timestamp":"2026-10-16T00:24:12+00:00"} |
| Assinatura esperada |
a05a474d5ebb41024d09060e29f531c7ae589fdd386dea27731abb1d06797a99 |
Se o seu código gerar exatamente essa assinatura com esses valores, o cálculo está certo.
Teste Local (ngrok)
# Instalar ngrok
ngrok http 3000
# Use a URL HTTPS gerada como webhook_url
# Ex: https://abc123.ngrok.io/webhook/flowinpay
O que vale testar antes de vender
- Assinatura errada → o seu endpoint responde 401 e não mexe no pedido
- O mesmo evento duas vezes → o pedido é liberado uma vez só
charge.expired chegando depois de charge.completed → o pedido continua pago
- Banco fora do ar → o seu endpoint responde 500 (e a FlowinPay reenvia)
Eventos e o que fazer com cada um
| Evento |
Quando |
Ação recomendada |
charge.created |
Cobrança criada |
Opcional: marcar que o QR Code foi gerado |
charge.completed |
Pagamento confirmado |
Marcar pago se ainda pendente e o valor bater, depois liberar acesso / enviar produto |
charge.expired |
Cobrança expirada |
Cancelar o pedido só se ainda pendente |
charge.cancelled |
Cobrança cancelada |
Cancelar o pedido só se ainda pendente |
charge.refunded |
Estorno processado |
Estornar o pedido só se estava pago |
webhook.test |
Botão Testar do painel |
Só responder 2xx |
Boas Práticas
- Verifique sempre a assinatura — antes de responder qualquer coisa além de 401
- Grave antes de responder 2xx — e responda 5xx se não conseguir gravar; o reenvio cuida do resto
- Descarte repetidos pelo
event_id — chave única na tabela de eventos
- Nunca regrida status — todo
UPDATE de pedido tem condição de status
- Confira o valor — o
value do evento tem que ser o total que o seu servidor calculou para o pedido
- Use HTTPS — a URL do webhook precisa ser HTTPS
- Guarde o corpo bruto — a tabela de eventos já serve de log para investigar
Troubleshooting
Webhook não está recebendo
- Verifique se a URL está correta, é HTTPS e está acessível pela internet
- Verifique se o servidor está rodando
- Teste com ngrok para ambientes locais
Assinatura inválida
- Verifique se o secret está correto — é o do webhook (
whsec_...), completo, com o prefixo. Não é a API Key (fpk_...). Se regenerou no painel, o antigo deixou de valer
- Verifique se está usando o body raw (não parseado e re-serializado)
- Compare com o exemplo fictício da seção Passo 4
Timeout
- Grave o evento e responda; deixe o trabalho pesado (e-mail, entrega, nota) para uma fila
- Uma inserção numa tabela leva milissegundos — se está estourando 10 segundos, o lento é outra coisa
Evento duplicado
- É esperado: o reenvio usa o mesmo
event_id (igual ao header X-FlowinPay-Delivery). A chave única da tabela webhook_events descarta o repetido
- Os
UPDATE com condição de status impedem liberar o mesmo pedido duas vezes mesmo que o descarte falhe
Taxas
Taxas
Consultar Taxas Ativas
GET /api/v1/fees/current
Endpoint público — não requer autenticação.
Response (200)
{
"fees": {
"percentual": "2.00",
"fixed_value": "1.00",
"withdrawal_fee": "2.00",
"minimum_charge": "2.00",
"maximum_charge": "150.00",
"minimum_withdrawal": "10.00",
"maximum_withdrawal": "1000.00"
}
}
Campos
| Campo |
Tipo |
Descrição |
percentual |
string |
Taxa percentual sobre cobranças (%) |
fixed_value |
string |
Taxa fixa por cobrança (R$) |
withdrawal_fee |
string |
Taxa fixa por saque (R$) |
minimum_charge |
string |
Valor mínimo de cobrança (R$) |
maximum_charge |
string |
Valor máximo de cobrança (R$) |
minimum_withdrawal |
string |
Valor mínimo de saque (R$) |
maximum_withdrawal |
string |
Valor máximo de saque (R$) |
Exemplo
curl -X GET "https://app.flowinpay.com.br/api/v1/fees/current" \
-H "Accept: application/json"
Página de Pagamento
Página Pública de Pagamento
Visão Geral
Ao criar uma cobrança, a FlowinPay gera um payment_link_url que pode ser compartilhado diretamente com o pagador. Essa página pública exibe o QR Code e o PIX copia-e-cola para pagamento.
GET /pay/{correlationId}
Essa é uma página HTML/SPA — não uma rota de API. O integrador apenas compartilha o link.
Fluxo
- Integrador cria cobrança via
POST /api/v1/charges
- Recebe
payment_link_url no response
- Compartilha o link com o pagador (WhatsApp, email, botão de pagamento, etc.)
- Pagador acessa o link → vê QR Code + PIX copia-e-cola + countdown de expiração
- Pagador paga → webhook
charge.completed é disparado automaticamente
O que o pagador vê
- Valor da cobrança
- QR Code do PIX
- Código PIX copia-e-cola (
br_code)
- Countdown de expiração (24h)
- Status do pagamento (aguardando → confirmado)
Endpoint Público da API
A página consulta o status da cobrança via endpoint público (sem autenticação):
GET /api/public/charge/{correlationId}
Response (200)
{
"charge": {
"id": 42,
"correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"value": "50.00",
"status": "active",
"br_code": "00020101021226580014br.gov.bcb.pix...",
"qr_code_image": "https://app.flowinpay.com.br/storage/qr/abc123.png",
"expires_at": "2026-06-06T13:00:00Z"
}
}
Rate limit: 30 requisições por minuto por IP.
Campos retornados (públicos)
| Campo |
Descrição |
value |
Valor da cobrança |
status |
Status atual (active, paid, expired) |
br_code |
PIX copia-e-cola |
qr_code_image |
URL da imagem do QR Code |
expires_at |
Data de expiração |
Nota: Dados sensíveis (customer, API key, etc.) não são expostos neste endpoint.
Erros
Erros
A API FlowinPay utiliza códigos de status HTTP padrão e retorna erros em formato JSON.
Formato do Erro
{
"message": "Descrição do erro",
"errors": {
"campo": ["Mensagem de validação"]
}
}
Códigos de Status
| Status |
Descrição |
200 |
Sucesso |
201 |
Criado com sucesso |
400 |
Requisição inválida |
401 |
Não autenticado |
403 |
Sem permissão |
404 |
Recurso não encontrado |
422 |
Erro de validação |
429 |
Rate limit excedido |
500 |
Erro interno do servidor |
Erros Comuns
401 - Não Autenticado
{
"message": "Unauthenticated."
}
Causas:
- App ID ausente no header
X-Api-Key
- App ID inválida ou revogada
- Formato incorreto (use
X-Api-Key: fpk_xxxx)
Solução:
# Verifique se a App ID está correta e ativa no painel
curl -H "X-Api-Key: fpk_xxxx" "https://app.flowinpay.com.br/api/v1/balance"
403 - Sem Permissão
{
"message": "Esta ação não é autorizada."
}
Causas:
- API Key sem permissão para o endpoint
- Usuário sem acesso ao recurso
Solução:
- Verifique as permissões da API Key
- Use uma chave com permissões adequadas
404 - Não Encontrado
{
"message": "No query results for model [App\\Models\\Charge] 999"
}
Causas:
- ID do recurso não existe
- Recurso pertence a outro usuário
Solução:
- Verifique se o ID está correto
- Consulte a listagem para IDs válidos
422 - Erro de Validação
{
"message": "O valor da cobrança é obrigatório.",
"errors": {
"value": ["O valor da cobrança é obrigatório."]
}
}
Erros de Validação Comuns:
Cobranças
| Campo |
Erro |
Solução |
value |
O valor da cobrança é obrigatório |
Envie o campo value |
value |
O valor mínimo é R$ 2,00 |
Aumente o valor |
value |
O valor máximo é R$ 150,00 |
Diminua o valor |
acquirer_id |
Selecione uma adquirente |
Envie acquirer_id: 1 |
acquirer_id |
Adquirente inválida |
Use um ID válido |
customer_email |
E-mail do cliente inválido |
Formato: user@example.com |
Saques
| Campo |
Erro |
Solução |
value |
Saldo insuficiente |
Verifique o saldo |
value |
Valor mínimo R$10 |
Aumente o valor |
pix_key |
Chave PIX obrigatória |
Envie a chave PIX |
pix_key_type |
Tipo inválido |
Use: cpf, cnpj, email, phone, random |
Webhooks
| Campo |
Erro |
Solução |
url |
URL inválida |
Use formato completo: https://... |
events |
Evento inválido |
Use eventos da lista disponível |
events |
Selecione pelo menos um |
Envie array com 1+ eventos |
429 - Rate Limit
{
"message": "Too Many Attempts.",
"retry_after": 45
}
Limites:
| Endpoint |
Limite |
| API v1 (todas rotas) |
60 req/min |
| Login/Registro |
10 req/min |
| Cobranças (painel) |
30 req/min |
| Página pública de pagamento |
30 req/min |
| Webhook receiver (adquirente) |
100 req/min |
Solução:
- Aguarde
retry_after segundos
- Implemente exponential backoff
- Use webhooks em vez de polling
500 - Erro Interno
{
"message": "Erro interno do servidor"
}
Causas:
- Erro na adquirente (Woovi)
- Timeout na API externa
- Falha temporária
Solução:
- Tente novamente em alguns segundos
- Verifique o status da API:
GET /api/health
- Se persistir, contate o suporte
Erros Específicos da Adquirente
Erro ao criar cobrança
{
"message": "Erro ao criar cobrança na adquirente"
}
Causas comuns:
- Chave PIX inválida
- Valor fora do limite
- Falha de conexão com Woovi
Solução:
- Verifique os dados da cobrança
- Tente com outro valor
- Aguarde e tente novamente
Boas Práticas
- Sempre verifique o status — Não assuma sucesso
- Trate erros de validação — Use o campo
errors para feedback
- Implemente retry — Para erros 429 e 500
- Log de erros — Registre erros para debugging
- Idempotência — Use
correlation_id para evitar duplicatas
Exemplo de Tratamento de Erros
JavaScript
async function createCharge(data) {
try {
const response = await fetch('/api/v1/charges', {
method: 'POST',
headers: {
'X-Api-Key': apiKey,
'Content-Type': 'application/json'
},
body: JSON.stringify(data)
});
if (!response.ok) {
const error = await response.json();
if (response.status === 422) {
// Erro de validação
console.error('Validação:', error.errors);
throw new Error(Object.values(error.errors).flat().join(', '));
}
if (response.status === 429) {
// Rate limit - aguardar
await new Promise(r => setTimeout(r, error.retry_after * 1000));
return createCharge(data); // Retry
}
throw new Error(error.message);
}
return await response.json();
} catch (error) {
console.error('Erro:', error.message);
throw error;
}
}
PHP
function createCharge(array $data): array {
$ch = curl_init('https://app.flowinpay.com.br/api/v1/charges');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => [
'X-Api-Key: ' . env('FLOWINPAY_API_KEY'),
'Content-Type: application/json',
'Accept: application/json',
],
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
if ($httpCode >= 400) {
$errorMessage = $result['message'] ?? 'Erro desconhecido';
if ($httpCode === 422) {
$errors = collect($result['errors'])->flatten()->implode(', ');
throw new Exception("Erro de validação: {$errors}");
}
if ($httpCode === 429) {
sleep($result['retry_after']);
return createCharge($data); // Retry
}
throw new Exception($errorMessage);
}
return $result;
}
Ambiente de testes
Ambiente de testes (sandbox)
Para homologar a sua integração sem movimentar dinheiro de verdade.
https://sandbox.flowinpay.com.br
O sandbox é uma cópia separada da FlowinPay, com banco de dados próprio. Tudo funciona como em produção — cobrança, split, saldo, saque, webhooks assinados, tarifas e limites —, mas nenhum Pix é real: os pagamentos são simulados por você.
|
Produção |
Sandbox |
| Endereço |
https://app.flowinpay.com.br |
https://sandbox.flowinpay.com.br |
| API |
https://app.flowinpay.com.br/api/v1 |
https://sandbox.flowinpay.com.br/api/v1 |
| Conta e API Key |
as suas (fpk_...) |
separadas — crie uma conta no sandbox; a chave começa com fpk_test_ |
| Pagamento |
Pix real |
você simula |
| Saque |
Pix real |
aprovado na hora, sem Pix |
| Verificação de identidade (KYC) |
análise de documentos |
já aprovada no cadastro |
| Webhooks |
assinados |
assinados do mesmo jeito, enviados para a sua URL |
Como testar
- Crie uma conta em
https://sandbox.flowinpay.com.br/register. Ela é independente da conta de produção.
- Gere uma API Key em Desenvolvedor → API Keys e cadastre o seu webhook na aba Webhooks.
- Crie uma cobrança normalmente, trocando só o endereço da API:
curl -X POST "https://sandbox.flowinpay.com.br/api/v1/charges" \
-H "X-Api-Key: fpk_xxxx" \
-H "Content-Type: application/json" \
-d '{ "value": 50.00 }'
- Simule o pagamento — pelo botão Simular pagamento no detalhe da cobrança, no painel, ou pela API:
curl -X POST "https://sandbox.flowinpay.com.br/api/v1/sandbox/charges/{id}/pay" \
-H "X-Api-Key: fpk_xxxx"
{id} aceita o id ou o correlation_id da cobrança. A chave precisa da permissão charge:create.
O pagamento simulado percorre o mesmo caminho de um Pix real: a cobrança vira paid, o saldo recebe o valor líquido (já descontada a tarifa), o split é distribuído entre os recebedores e o webhook charge.completed é enviado, assinado, para a sua URL.
- Confira o saldo, o extrato e o webhook recebido. Para testar o saque, peça um saque normalmente: ele é aprovado na hora e o webhook
withdrawal.completed é enviado.
Resposta do "simular pagamento"
{
"message": "Pagamento simulado. O saldo foi creditado e o webhook charge.completed foi enviado.",
"charge": {
"id": 12,
"correlation_id": "pedido-123",
"status": "paid",
"value": "50.00",
"fee_value": "2.00",
"paid_at": "2026-10-16T15:20:00.000000Z",
"end_to_end_id": "E0000000020261016152000ABC123DEF45"
}
}
Cobrança que não está aguardando pagamento (já paga, expirada ou cancelada) responde 422. Cobrança de outra conta responde 404.
Testando o split
Crie uma segunda conta no sandbox (por exemplo, a de um parceiro ou motorista) e use o public_id dela como recebedor:
{
"value": 100.00,
"split": [{ "recipient": "PUBLIC_ID_DA_SEGUNDA_CONTA", "type": "percentage", "value": 10 }]
}
Depois de simular o pagamento, confira o extrato das duas contas.
O que é diferente da produção
- A chave de teste só funciona no sandbox, e a de produção só na produção. Usar a chave do ambiente errado responde 401 dizendo de qual ambiente ela é — é o erro mais comum de quem acabou de homologar e trocou o endereço, mas esqueceu a chave.
- O copia e cola não pode ser pago. Ele tem o formato certo (os leitores de QR Code aceitam), mas a chave Pix é inválida de propósito: o app do banco recusa. Não tente pagar — use o "simular pagamento".
- Contestações (MED), Pix Automático e nota fiscal não são simulados.
- Os dados do sandbox podem ser apagados de tempos em tempos. Não guarde nada importante lá.
- Tarifas e limites são os mesmos da produção, e o
GET /api/v1/fees/current mostra os da sua conta no sandbox.
Indo para produção
Troque o endereço da API para https://app.flowinpay.com.br/api/v1, use a API Key de produção e cadastre o webhook de produção (o secret é outro). O endpoint /sandbox/charges/{id}/pay não existe em produção.
Central de ajuda · FlowinPay · Criar conta