KaironPay API

Documentacao completa da API de pagamentos PIX do KaironPay.

Base URL: https://api.kaironpay.com.br/api/v1/client

Sobre a plataforma

O KaironPay oferece uma API REST completa para integrar cobranças PIX, saques, clientes e webhooks ao seu sistema. Multi-provedor, segura e em tempo real.

Cobranças PIX

QR Code dinamico com confirmacao em segundos

Saques PIX

Transferencias automaticas para qualquer chave PIX

Webhooks

Notificações em tempo real para cada evento

Multi-Provedor

Woovi, Rapdyn, Venit, Asaas, GoGate e mais

Valores monetários: Todos os valores na API são em centavos. Ex: R$ 10,00 = 1000.

Códigos de Status HTTP

Código	Significado
200	Sucesso
201	Recurso criado
400	Dados inválidos
401	Não autenticado
403	Sem permissão
404	Não encontrado
429	Rate limit excedido
500	Erro interno

Autenticacao

Todas as requisicoes a API devem incluir sua API Key no header Authorization.

Authorization: Bearer cmd_xxxxxxxxxxxxxxxxxxxxx

Como obter sua API Key

Acesse o Painel do KaironPay
Va em Configuracoes → API Key
Copie a chave no formato cmd_*

Formato da API Key

Todas as API Keys comecam com o prefixo cmd_ seguido de caracteres alfanumericos. Exemplo: cmd_a1B2c3D4e5F6g7H8i9J0

Exemplos de uso

cURL

curl -X POST https://api.kaironpay.com.br/api/v1/client/charges \
  -H "Authorization: Bearer cmd_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{"value": 1000, "comment": "Pedido #123"}'

JavaScript / Node.js

const res = await fetch("https://api.kaironpay.com.br/api/v1/client/charges", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ value: 1000, comment: "Pedido #123" })
});
const data = await res.json();
console.log(data.data.brCode); // Codigo PIX copia-e-cola

Python

import requests

resp = requests.post(
    "https://api.kaironpay.com.br/api/v1/client/charges",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"value": 1000, "comment": "Pedido #123"}
)
print(resp.json()["data"]["brCode"])

PHP

$ch = curl_init("https://api.kaironpay.com.br/api/v1/client/charges");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $apiKey",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "value" => 1000, "comment" => "Pedido #123"
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);

Erros de autenticacao

Status	Codigo	Descricao
401	auth_missing	Header Authorization nao enviado
401	invalid_auth_format	Formato invalido (use `Bearer cmd_xxx`)
401	invalid_api_key	API Key nao encontrada ou inativa
401	api_key_expired	API Key expirada
429	rate_limit	Limite de requisicoes excedido

Exemplo de erro 401

{ "error": "invalid_api_key", "message": "API Key invalida ou inativa" }

Seguranca: Nunca exponha sua API Key em codigo client-side (front-end, apps mobile). Use sempre em backend (server-to-server). Cada chave tem rate limit configuravel.

Rate Limit: Padrao de 10.000 requisicoes por janela de 15 minutos. Pode ser ajustado por conta no painel admin.

Cobrancas PIX

Crie cobrancas PIX com QR Code dinamico, liste, consulte e cancele cobrancas.

POST/api/v1/client/charges

Cria uma cobranca PIX e retorna o QR Code e o codigo copia-e-cola (brCode) para pagamento. A cobranca fica com status ACTIVE ate ser paga ou expirar.

Parametros do body (JSON)

Parametro	Tipo		Descricao
value	number	obrigatorio	Valor em centavos. Ex: `1500` = R$ 15,00. Minimo: 1 centavo.
comment	string		Descricao da cobranca exibida ao pagador
correlationID	string		ID unico da sua aplicacao (min 26 chars). Se nao informado, sera gerado automaticamente.
customer	object		Dados do pagador (obrigatorio para maioria dos provedores)
customer.name	string		Nome completo do pagador
customer.taxID	string		CPF ou CNPJ do pagador (apenas numeros)
customer.email	string		Email do pagador (formato valido)
customer.phone	string		Telefone do pagador
expiresDate	string		Data de expiracao (ISO 8601). Ex: `2026-04-18T23:59:59Z`

Idempotencia: Se voce enviar o mesmo correlationID, a API retorna a cobranca existente ao inves de criar uma nova (status 200).

Exemplo de requisicao

curl -X POST https://api.kaironpay.com.br/api/v1/client/charges \
  -H "Authorization: Bearer cmd_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 1500,
    "comment": "Pedido #456",
    "customer": {
      "name": "Joao Silva",
      "taxID": "12345678900",
      "email": "joao@email.com"
    }
  }'

Resposta de sucesso (201 Created)

{
  "success": true,
  "data": {
    "correlationID": "CMD20260417013000a1b2c3d4e5f6",
    "value": 1500,
    "status": "ACTIVE",
    "brCode": "00020101021226940014br.gov.bcb.pix2572...",
    "qrCodeImage": "data:image/png;base64,iVBORw0KGgo...",
    "paymentLinkUrl": "https://api.kaironpay.com.br/abc123",
    "expiresAt": "2026-04-18T23:59:59.000Z",
    "createdAt": "2026-04-17T01:30:00.000Z"
  },
  "brCode": "00020101021226940014br.gov.bcb.pix2572...",
  "qrCodeImage": "data:image/png;base64,iVBORw0KGgo...",
  "usedProvider": "RAPDYN",
  "fallbackUsed": false
}

Campos da resposta

Campo	Tipo	Descricao
data.correlationID	string	ID unico da cobranca (use para consultar status)
data.value	number	Valor em centavos
data.status	string	`ACTIVE` (aguardando pagamento)
data.brCode	string	Codigo PIX copia-e-cola (EMV)
data.qrCodeImage	string	QR Code em base64 (PNG). Use em `<img src="...">`
data.paymentLinkUrl	string	Link de pagamento (quando disponivel)
data.expiresAt	string	Data de expiracao (ISO 8601)
usedProvider	string	Provedor que processou (RAPDYN, WOOVI, etc.)
fallbackUsed	boolean	`true` se o provedor principal falhou e um fallback foi usado

GET/api/v1/client/charges

Lista todas as cobrancas da conta autenticada com filtros e paginacao.

Query parameters

Parametro	Tipo	Default	Descricao
skip	number	0	Offset para paginacao
limit	number	100	Maximo de resultados (max: 500)
status	string		Filtro: `ACTIVE`, `COMPLETED`, `EXPIRED`, `REFUNDED`
start_date	string		Data inicial (ISO 8601)
end_date	string		Data final (ISO 8601)

Resposta (200)

{
  "success": true,
  "data": [
    {
      "correlationID": "charge_abc123...",
      "value": 1500,
      "status": "COMPLETED",
      "createdAt": "2026-04-17T01:30:00Z",
      "paidAt": "2026-04-17T01:31:00Z",
      "endToEndId": "E12345678...",
      "customer": { "name": "Joao", "taxID": "123..." },
      "feeAmount": 45,
      "netAmount": 1455,
      "isRefunded": false
    }
  ],
  "pageInfo": {
    "skip": 0, "limit": 100,
    "totalCount": 42,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

GET/api/v1/client/charges/:correlationID

Consulta uma cobranca especifica pelo correlationID. Retorna todos os campos incluindo brCode, qrCodeImage, dados do cliente e informacoes de reembolso.

Exemplo

curl https://api.kaironpay.com.br/api/v1/client/charges/charge_abc123 \
  -H "Authorization: Bearer cmd_sua_api_key"

DELETE/api/v1/client/charges/:correlationID

Cancela uma cobranca ativa. Disponivel apenas para o provedor Woovi.

Resposta (200)

{ "success": true, "message": "Charge deleted successfully" }

Status possiveis: ACTIVE (aguardando pgto), COMPLETED (pago), EXPIRED (expirado), REFUNDED (reembolsado), CANCELLED (cancelado).

Clientes

Cadastre e consulte clientes (pagadores) vinculados a sua conta.

Nota: Para a maioria dos provedores, clientes sao criados automaticamente ao criar uma cobranca com o campo customer. O endpoint de criacao manual esta disponivel apenas para o provedor Woovi.

POST/api/v1/client/customers

Cadastra um novo cliente manualmente. Util para pre-cadastrar pagadores antes de criar cobrancas.

Parametros do body (JSON)

Parametro	Tipo		Descricao
name	string	obrigatorio	Nome completo do cliente
taxID	string	obrigatorio	CPF ou CNPJ (apenas numeros)
email	string		Email valido
phone	string		Telefone com DDD
correlationID	string		ID unico na sua aplicacao
address	object		Endereco completo
address.zipcode	string		CEP
address.street	string		Rua
address.number	string		Numero
address.neighborhood	string		Bairro
address.city	string		Cidade
address.state	string		UF (2 letras)

Exemplo

curl -X POST https://api.kaironpay.com.br/api/v1/client/customers \
  -H "Authorization: Bearer cmd_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Oliveira",
    "taxID": "98765432100",
    "email": "maria@email.com",
    "phone": "+5511999887766"
  }'

Resposta (201 Created)

{
  "success": true,
  "data": {
    "name": "Maria Oliveira",
    "taxID": "98765432100",
    "email": "maria@email.com",
    "correlationID": "cust_abc123..."
  }
}

GET/api/v1/client/customers

Lista todos os clientes cadastrados na conta.

Query parameters

Parametro	Tipo	Default	Descricao
skip	number	0	Offset para paginacao
limit	number	100	Maximo de resultados

Saques e Transferencias

Envie PIX para qualquer chave — saques automaticos ou com aprovacao manual via API.

Modos de aprovacao: auto (padrao) — saque e processado imediatamente. manual — saque fica pendente ate aprovacao do admin no painel.

POST/api/v1/client/payouts

Cria um saque/transferencia PIX. O valor e debitado do saldo disponivel. A taxa e calculada automaticamente conforme configuracao da conta.

Parametros do body (JSON)

Parametro	Tipo		Descricao
value	number	obrigatorio	Valor em centavos. Minimo: `100` (R$ 1,00)
pixKey	string	obrigatorio	Chave PIX de destino
pixKeyType	string	obrigatorio	Tipo da chave (ver tabela abaixo)
description	string		Descricao/observacao do saque
correlationID	string		ID unico para evitar duplicatas

Tipos de chave PIX

pixKeyType	Formato	Exemplo
cpf	11 digitos	`12345678900`
cnpj	14 digitos	`12345678000190`
email	Email valido	`joao@email.com`
phone	+55 + DDD + numero	`+5511999887766`
evp	Chave aleatoria (UUID)	`a1b2c3d4-e5f6-...`

Exemplo de requisicao

curl -X POST https://api.kaironpay.com.br/api/v1/client/payouts \
  -H "Authorization: Bearer cmd_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 5000,
    "pixKey": "11999887766",
    "pixKeyType": "phone",
    "description": "Pagamento fornecedor"
  }'

Resposta — Modo automatico (201 Created)

{
  "success": true,
  "data": {
    "reference_code": "payout_x7k9m2a1b3...",
    "amount": 50.00,
    "net_amount": 48.50,
    "fee": 1.50,
    "status": "processing",
    "source": "API",
    "message": "Payout enqueued for processing"
  }
}

Resposta — Modo manual (201 Created)

{
  "success": true,
  "data": {
    "reference_code": "payout_y8j3n1...",
    "amount": 50.00,
    "net_amount": 48.50,
    "fee": 1.50,
    "status": "pending_approval",
    "source": "API",
    "message": "Withdrawal created and awaiting approval"
  }
}

Erros comuns: 400 saldo insuficiente, 400 limite diario excedido, 403 saques bloqueados, 409 correlationID duplicado.

GET/api/v1/client/payouts

Lista todos os saques da conta com filtros e paginacao.

Query parameters

Parametro	Tipo	Default	Descricao
skip	number	0	Offset para paginacao
limit	number	100	Maximo de resultados (max: 500)
status	string		Filtro: `COMPLETED`, `PENDING`, `FAILED`, `REJECTED`
start_date	string		Data inicial (ISO 8601)
end_date	string		Data final (ISO 8601)

Resposta (200)

{
  "success": true,
  "data": [
    {
      "referenceCode": "payout_x7k9m2...",
      "value": 5000,
      "status": "COMPLETED",
      "pixKey": "119****7766",
      "pixKeyType": "phone",
      "recipientName": "Maria Oliveira",
      "createdAt": "2026-04-17T03:00:00Z",
      "completedAt": "2026-04-17T03:00:05Z",
      "errorMessage": null
    }
  ],
  "pagination": { "skip": 0, "limit": 100, "hasMore": false }
}

GET/api/v1/client/payouts/:reference_code

Consulta o status de um saque especifico. Aceita reference_code ou correlationID.

Resposta (200)

{
  "success": true,
  "data": {
    "reference_code": "payout_x7k9m2...",
    "amount": 50.00,
    "net_amount": 48.50,
    "fee": 1.50,
    "status": "completed",
    "pix_key": "11999887766",
    "pix_key_type": "phone",
    "created_at": "2026-04-17T03:00:00Z",
    "completed_at": "2026-04-17T03:00:05Z",
    "provider": "RAPDYN",
    "error_message": null
  }
}

Status do saque: pending_approval → processing → completed | failed | rejected

Reembolsos

Estorne total ou parcialmente cobrancas ja pagas. O valor e devolvido ao pagador via PIX.

Disponibilidade: Reembolsos via API estao disponiveis para os provedores Woovi e Venit. Para outros provedores, solicite reembolso manualmente pelo painel ou contate o suporte.

POST/api/v1/client/refunds

Cria um reembolso para uma cobranca ja paga (COMPLETED). Suporta reembolso total ou parcial.

Parametros do body (JSON)

Parametro	Tipo		Descricao
correlationID	string	obrigatorio	correlationID da cobranca original que sera reembolsada
value	number	obrigatorio	Valor do reembolso em centavos. Para reembolso total, use o mesmo valor da cobranca.
comment	string		Motivo do reembolso (ex: "Produto com defeito")

Exemplo — Reembolso parcial

curl -X POST https://api.kaironpay.com.br/api/v1/client/refunds \
  -H "Authorization: Bearer cmd_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "correlationID": "charge_abc123...",
    "value": 500,
    "comment": "Desconto por atraso na entrega"
  }'

Exemplo — Reembolso total

curl -X POST https://api.kaironpay.com.br/api/v1/client/refunds \
  -H "Authorization: Bearer cmd_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "correlationID": "charge_abc123...",
    "value": 1500,
    "comment": "Cancelamento do pedido"
  }'

Resposta (201 Created)

{
  "success": true,
  "data": {
    "id": "refund_xyz789...",
    "status": "REFUNDED",
    "value": 500,
    "correlationID": "charge_abc123...",
    "createdAt": "2026-04-17T04:00:00.000Z"
  }
}

Regras de reembolso

Regra	Descricao
Status obrigatorio	Apenas cobrancas com status `COMPLETED` podem ser reembolsadas
Valor maximo	O valor do reembolso nao pode exceder o valor original da cobranca
Reembolso parcial	Suportado — envie um valor menor que o original
Limite por cobranca	Apenas 1 reembolso por cobranca
Webhook	Evento `TRANSACTION_REFUNDED` e enviado apos o processamento

Webhooks

Receba notificações em tempo real quando eventos ocorrem. O KaironPay envia um POST HTTP para a URL cadastrada com os dados do evento.

Como funciona

Quando um evento ocorre (pagamento confirmado, saque realizado, etc.), o KaironPay envia automaticamente um POST HTTP para cada URL de webhook cadastrada. O payload é assinado com HMAC-SHA256 para garantir autenticidade.

Cadastre sua URL de webhook no painel (Configurações → Webhook)
Escolha os eventos que deseja receber
Quando o evento ocorrer, o KaironPay envia um POST para sua URL
Valide a assinatura X-Command-Signature com seu secret
Retorne HTTP 2xx em até 5 segundos

Headers enviados em cada webhook

Header	Descrição	Exemplo
Content-Type	Tipo do conteúdo	`application/json`
X-Command-Signature	Assinatura HMAC-SHA256 do body (hex)	`a1b2c3d4e5...`
X-Command-Timestamp	Timestamp Unix da assinatura (segundos)	`1713318600`
X-Command-Algorithm	Algoritmo usado na assinatura	`HMAC-SHA256`
X-Command-Event	Tipo do evento	`TRANSACTION_COMPLETED`
User-Agent	Identificador do remetente	`Command-Webhook/1.0`

Todos os eventos disponíveis

Evento interno	Evento no payload	Descrição
Cobranças (PIX In)
TRANSACTION_CREATED	`PayInCreated`	Cobrança PIX criada, aguardando pagamento
TRANSACTION_COMPLETED	`PayInCompleted`	Pagamento PIX confirmado com sucesso
TRANSACTION_EXPIRED	`PayInExpired`	Cobrança expirou sem pagamento
TRANSACTION_CANCELLED	`PayInCancelled`	Cobrança cancelada
TRANSACTION_FAILED	`PayInFailed`	Falha no processamento da cobrança
TRANSACTION_REFUNDED	`PayInRefunded`	Cobrança reembolsada (total ou parcial)
TRANSACTION_CHARGEBACK	`PayInChargeback`	Contestação/disputa recebida
Saques (PIX Out)
PAYOUT_CREATED	`PayOutCreated`	Saque criado, aguardando aprovação/processamento
PAYOUT_APPROVED	`PayOutApproved`	Saque aprovado (quando aprovação manual está ativa)
PAYOUT_COMPLETED	`PayOutCompleted`	Saque/transferência PIX concluído com sucesso
PAYOUT_FAILED	`PayOutFailed`	Saque falhou (chave inválida, sem saldo, etc.)
PAYOUT_REJECTED	`PayOutRejected`	Saque rejeitado pelo admin
PAYOUT_REFUNDED	`PayOutRefunded`	Saque devolvido pelo banco destinatário

Formato do payload: Todos os webhooks seguem a mesma estrutura: { event, timestamp, data }. O campo data contém os detalhes do evento. Valores monetários em data são em reais (não centavos).

Payloads de Cobrança (PIX In)

POSTTRANSACTION_COMPLETEDPagamento confirmado

Enviado quando um pagamento PIX é confirmado. Este é o evento mais importante — use-o para liberar o produto/serviço ao cliente.

Campo	Tipo	Descrição
event	string	`"PayInCompleted"`
timestamp	string	Data/hora ISO 8601 do envio
data.id	string	ID interno da cobrança
data.txid	string	correlationID da cobrança
data.amount	number	Valor em reais (ex: 100.00)
data.status	string	`"paid"`
data.payer.name	string	Nome de quem pagou o PIX
data.payer.document_number	string	CPF/CNPJ de quem pagou
data.payer.account_bank	string	Banco de origem (se disponível)
data.paidAt	string	Data/hora do pagamento (ISO 8601)
data.endToEndId	string	ID E2E do PIX (rastreabilidade BACEN)
data.provider	string	Provedor que processou (RAPDYN, WOOVI, etc.)
data.comment	string	Descrição da cobrança

Exemplo completo

{
  "event": "PayInCompleted",
  "timestamp": "2026-04-17T01:30:00.000Z",
  "data": {
    "id": "charge_qrpzwB9ZxePks2tiiVTrW",
    "txid": "charge_qrpzwB9ZxePks2tiiVTrW",
    "payer": {
      "name": "João Silva",
      "document_number": "12345678900",
      "account_bank": "Banco do Brasil",
      "account_ispb": "00000000"
    },
    "amount": 100.00,
    "status": "paid",
    "paidAt": "2026-04-17T01:30:00.000Z",
    "refundedAt": null,
    "endToEndId": "E123456782026041701300000001",
    "provider": "RAPDYN",
    "comment": "Pedido #456"
  }
}

POSTTRANSACTION_CREATEDCobrança criada

Enviado quando uma nova cobrança PIX é criada. Útil para tracking.

{
  "event": "PayInCreated",
  "timestamp": "2026-04-17T01:00:00.000Z",
  "data": {
    "id": "charge_abc123...",
    "txid": "charge_abc123...",
    "payer": { "name": "João Silva", "document_number": "12345678900" },
    "amount": 100.00,
    "status": "pending",
    "paidAt": null,
    "endToEndId": null,
    "provider": "RAPDYN",
    "comment": "Pedido #456"
  }
}

POSTTRANSACTION_REFUNDEDReembolso processado

Enviado quando uma cobrança é reembolsada (total ou parcialmente).

{
  "event": "PayInRefunded",
  "timestamp": "2026-04-17T02:00:00.000Z",
  "data": {
    "id": "charge_abc123...",
    "txid": "charge_abc123...",
    "payer": { "name": "João Silva", "document_number": "12345678900" },
    "amount": 100.00,
    "status": "refunded",
    "paidAt": "2026-04-17T01:30:00.000Z",
    "refundedAt": "2026-04-17T02:00:00.000Z",
    "endToEndId": "E123456782026041701300000001",
    "provider": "RAPDYN",
    "comment": "Pedido #456"
  }
}

POSTTRANSACTION_EXPIRED / CANCELLED / FAILED

Mesmo formato do TRANSACTION_COMPLETED, mas com status diferente:

Evento	event no payload	data.status
TRANSACTION_EXPIRED	`PayInExpired`	`"expired"`
TRANSACTION_CANCELLED	`PayInCancelled`	`"cancelled"`
TRANSACTION_FAILED	`PayInFailed`	`"failed"`
TRANSACTION_CHARGEBACK	`PayInChargeback`	`"pending"`

Payloads de Saque (PIX Out)

Nota: Payloads de saque têm campos diferentes dos de cobrança. Os valores são em centavos (diferente das cobranças que vêm em reais).

POSTPAYOUT_COMPLETEDSaque concluído

Enviado quando um saque PIX é processado e confirmado com sucesso.

Campo	Tipo	Descrição
data.referenceCode	string	ID interno do saque
data.correlationID	string	ID de correlação
data.value	number	Valor bruto em centavos
data.netAmount	number	Valor líquido em centavos (após taxas)
data.feeAmount	number	Taxa cobrada em centavos
data.status	string	`"COMPLETED"`
data.pixKey	string	Chave PIX de destino (parcialmente mascarada)
data.pixKeyType	string	Tipo da chave: cpf, cnpj, email, phone, random
data.endToEndId	string	ID E2E do PIX (rastreabilidade BACEN)
data.completedAt	string	Data/hora da conclusão (ISO 8601)

Exemplo completo

{
  "event": "PayOutCompleted",
  "timestamp": "2026-04-17T03:00:00.000Z",
  "data": {
    "referenceCode": "payout_x7k9m2...",
    "correlationID": "payout_x7k9m2...",
    "value": 10000,
    "netAmount": 9850,
    "feeAmount": 150,
    "status": "COMPLETED",
    "pixKey": "119****9999",
    "pixKeyType": "phone",
    "endToEndId": "E123456782026041703000000001",
    "providerTransactionId": "txn_provider_abc",
    "completedAt": "2026-04-17T03:00:00.000Z"
  }
}

POSTPAYOUT_APPROVEDSaque aprovado

Enviado quando um saque é aprovado pelo admin (apenas quando aprovação manual está ativa).

{
  "event": "PayOutApproved",
  "timestamp": "2026-04-17T02:50:00.000Z",
  "data": {
    "referenceCode": "payout_x7k9m2...",
    "value": 10000,
    "netAmount": 9850,
    "feeAmount": 150,
    "status": "APPROVED",
    "pixKey": "119****9999",
    "pixKeyType": "phone",
    "approvedAt": "2026-04-17T02:50:00.000Z"
  }
}

POSTPAYOUT_FAILEDSaque falhou

Enviado quando um saque falha no processamento (chave inválida, sem saldo no provedor, etc.).

{
  "event": "PayOutFailed",
  "timestamp": "2026-04-17T03:05:00.000Z",
  "data": {
    "referenceCode": "payout_y8j3n1...",
    "value": 5000,
    "netAmount": 4900,
    "feeAmount": 100,
    "status": "FAILED",
    "pixKey": "abc****xyz",
    "pixKeyType": "email",
    "failedAt": "2026-04-17T03:05:00.000Z",
    "errorMessage": "Chave PIX não encontrada"
  }
}

POSTPAYOUT_REJECTEDSaque rejeitado

Enviado quando um saque é rejeitado pelo admin.

{
  "event": "PayOutRejected",
  "timestamp": "2026-04-17T03:10:00.000Z",
  "data": {
    "referenceCode": "payout_z2m5p8...",
    "value": 50000,
    "netAmount": 49500,
    "feeAmount": 500,
    "status": "REJECTED",
    "pixKey": "123****890",
    "pixKeyType": "cpf",
    "rejectedAt": "2026-04-17T03:10:00.000Z",
    "rejectReason": "Valor acima do limite diário"
  }
}

Validação de assinatura

Sempre valide a assinatura X-Command-Signature antes de processar o webhook. Use seu Webhook Secret (configurado no painel) para verificar.

Node.js

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature), Buffer.from(expected)
  );
}

app.post('/webhook/command', (req, res) => {
  const sig = req.headers['x-command-signature'];
  if (!verifyWebhook(req.rawBody, sig, 'seu_secret')) {
    return res.status(401).send('Invalid signature');
  }
  const { event, data } = req.body;
  console.log(`Evento: ${event}, ID: ${data.id || data.referenceCode}`);
  res.status(200).send('OK');
});

Retentativas e boas práticas

Configuração	Valor
Timeout por tentativa	5 segundos
Retentativas em caso de falha	Até 3 vezes com backoff exponencial
Circuit breaker	Ativa após 15 falhas em 2 minutos
Resposta esperada	HTTP 2xx (200, 201, 204)
Reenvio manual	Disponível no painel (Webhooks → Histórico)

Idempotência: Seu endpoint pode receber o mesmo evento mais de uma vez (retentativas). Use o campo data.id ou data.referenceCode como chave de idempotência para evitar processar duplicatas.