Integrate PIX into your application with SymbolPay

Introduction#

A SymbolPay é uma gateway de pagamentos PIX B2B. O comerciante cria cobranças a partir do painel autenticado ou via links de pagamento públicos; o pagador paga o QR Code e a confirmação chega por webhook, credita o saldo do comerciante. O repasse é solicitado na página de saques.

Existem dois modos de uso:

• • Painel do comerciante (autenticado por sessão) — criação de cobranças, links, saques e gestão de conta.
• • Checkout público via link /pay/:slug — o pagador não precisa de conta.

A taxa é fixa: R$ 0,65 por cobrança recebida e R$ 0,65 por saque. O valor mínimo de cobrança e saque é R$ 1,00. A validade padrão é de 30 minutos; no painel, você também pode escolher 1 hora ou 24 horas.

Environments#

As chaves de API usam prefixo wz_live_ (produção) ou wz_test_ (teste). Ambas apontam para o mesmo app; o ambiente é definido pelo prefixo da chave.

Authentication#

A SymbolPay usa três modelos de autenticação, um para cada superfície:

• 1. Painel e funções do gateway — sessão do usuário autenticado (login por e-mail/senha ou Google) ou chave de API no header Authorization: Bearer wz_live_.... As funções gatewayCreateCharge e gatewayWithdraw aceitam ambos os métodos e validam o status da conta.
• 2. Checkout público — sem autenticação do pagador. As funções getPublicPaymentLink e gatewayCreateChargeFromLink rodam como serviço e validam apenas o link e o comerciante.
• 3. Webhook de entrada — assinado em HMAC-SHA256 (header x-goatpay-signature).

Create charge#

O comerciante autenticado cria uma cobrança PIX no painel (/cobrancas/nova). A função gatewayCreateCharge valida o comerciante, calcula a taxa e devolve o copia e cola + QR Code.

Parâmetros do body (JSON)

• amount number · obrigatório — Valor em reais (mín. R$ 1,00)
• description string — Descrição da cobrança (máx. 120 chars)
• external_reference string — ID do pedido no seu sistema (máx. 60 chars, volta no webhook)
• payer_name string — Nome do pagador
• payer_email string — E-mail do pagador
• payer_document string — CPF/CNPJ do pagador (só dígitos)
• fee_payer enum — "merchant" (padrão, taxa descontada do recebimento) ou "client" (cliente paga a taxa)

{
  "id": "chg_abc123",
  "goatpay_id": "pay_xyz",
  "copy_paste": "00020126...",
  "qrcode_url": "https://api.goatpay.com.br/qr/pay_xyz.png",
  "expires_at": "2026-10-04T20:30:00Z",
  "fee_payer": "merchant"
}

Payment links#

Crie um link reutilizável no painel (/links-pagamento) e compartilhe a URL https://wavez.online/pay/:slug por qualquer canal. O pagador abre, preenche os dados e paga — sem login.

Fluxo do checkout público

1. getPublicPaymentLink — consulta o link pelo slug e devolve nome, valor, descrição e marca do comerciante.
2. gatewayCreateChargeFromLink — valida o link (ativo, não expirado, dentro do limite de usos), cria a cobrança PIX e devolve o QR Code.

Track status#

O status de cada cobrança é atualizado automaticamente pelo webhook de entrada e aparece no painel em /cobrancas. Os status possíveis são:

• pendente — cobrança gerada, aguardando pagamento
• pago — pagamento confirmado e saldo creditado
• expirado — cobrança expirou sem pagamento
• cancelado — cobrança cancelada

Inbound webhook#

Eventos de pagamento chegam na função goatpayWebhook, que valida a assinatura HMAC-SHA256 no header x-goatpay-signature (formato sha256=...) e processa o evento de forma idempotente.

Eventos processados

• payment.paid — marca a cobrança como pago e credita o saldo do comerciante
• payment.pix.expired — marca a cobrança como expirado
• transfer.completed — marca o saque como pago e libera o saldo reservado
• transfer.failed — rejeita o saque e devolve o valor ao saldo disponível

{
  "event": "payment.paid",
  "data": { "id": "pay_xyz", "status": "paid" }
}

Outbound webhook (SYMBOL → you)#

No painel (/webhooks) você cadastra uma URL HTTPS de destino e seleciona os eventos. Um segredo de assinatura é gerado no servidor com entropia criptográfica e exibido uma única vez.

Eventos selecionáveis

• charge.paid
• charge.expired
• charge.cancelled
• withdrawal.paid

Cashout and withdrawal#

O comerciante solicita o saque do saldo disponível no painel (/saques). A função gatewayWithdraw reserva o valor de forma atômica, transfere para a chave PIX cadastrada no perfil do comerciante e desconta a taxa fixa de R$ 0,65.

{
  "id": "wdw_xyz789",
  "status": "pendente"
}

Error codes#

Os erros retornam HTTP apropriado (400, 401, 403, 404, 409, 429, 500, 502) e um objeto JSON com o campo error em português.

Security#

• Row-Level Security por comerciante: cobranças, saques, links e chaves só são visíveis para o dono ou administrador.
• Webhook de entrada assinado em HMAC-SHA256 com validação fail-closed (segredo ausente nunca valida).
• Proteção SSRF no cadastro de webhooks: HTTPS obrigatório e bloqueio de hosts internos (localhost, faixas privadas, link-local).
• Reserva atômica de saldo nos saques e idempotência nas transições de status evitam duplo crédito e saques duplicados.
• Chaves de API com hash SHA-256: só o prefixo e o hash são armazenados; a chave crua é exibida uma única vez.
• Slug de link único validado no servidor para evitar desvio de cobranças públicas para outro comerciante.

Service status#

Acompanhe a disponibilidade dos serviços da SymbolPay em tempo real na página pública de status.