Visão geral e arquitetura

O SharkPay é um gateway de pagamentos com uma API HTTP/JSON aberta. Seu sistema cria cobranças e saques, consulta o resultado e recebe eventos assinados — sem depender de plataforma, SDK ou fornecedor específico.

Como funciona

1. Você obtém as chaves no painel (chave pública + chave secreta) e troca por um token Bearer em POST /api/auth.
2. Seu servidor cria a cobrança (Pix, boleto ou cartão) ou um saque Pix. O SharkPay reserva/valida os valores e aciona o provedor de pagamento habilitado na sua conta.
3. O cliente paga pelo meio escolhido. O provedor avisa o SharkPay, que confirma o pagamento de forma atômica (sem crédito duplicado).
4. Você é avisado por webhook assinado (invoice.paid, pixout.paid…) e pode conferir o estado a qualquer momento por consulta.

Arquitetura de integração

Seu sistema (backend)                      SharkPay                         Provedores
 ─────────────────────                      ────────                         ──────────
 POST /api/auth  ───────────────────────►   valida chaves, emite token
 POST /api/pix/create (Idempotency-Key) ►   cria cobrança  ───────────────►  banco / adquirente
                                            ◄───────────────  QR Code / boleto / autorização
 ◄── 200 {reference, copy, qrcode}
                                            ◄── notificação de pagamento ──  (callback do provedor, autenticado)
                                            confirma + registra no livro-razão
 ◄── webhook invoice.paid (assinado) ────
 GET /api/invoice/ref/{ref}  ───────────►   estado atual (fonte da verdade)

• Sempre do servidor. A chave secreta e o token nunca devem existir em navegador ou app. Apps móveis falam com o seu backend, que fala com o SharkPay.
• Formato. JSON em UTF-8 (Content-Type: application/json). Valores monetários são decimais com ponto ("190.00" nas respostas), na moeda da conta.
• Fonte da verdade. O estado da cobrança no SharkPay. O redirecionamento do cliente ao seu site não prova pagamento.

Recursos disponíveis