Adquirentes e PayGate

Adquirentes são os bancos/provedores que efetivamente movimentam o dinheiro por trás da API. Esta página descreve o padrão usado por Banco do Brasil, FitBank, Cielo e PayGate — e como adicionar o próximo sem tocar nos existentes. Para quem integra via API nada muda: as rotas e payloads públicos são os mesmos.

O padrão

Peça	Onde fica	Responsabilidade
Catálogo	AcquirerRegistry	Lista de adquirentes, campos de credencial, capacidades, ambientes e limitações (mostrados no painel).
Credenciais	AcquirerCredentials	Armazenamento criptografado (APP_KEY) por adquirente e ambiente, com versão anterior guardada; máscara para exibição.
Módulo do provedor	app/Lib/Pix/Banks/Pix{Nome}	Implementa IPix (e IPixReferenced quando aceita referência própria). Isola autenticação, endpoints, erros e logs.
Fábrica	PixGateway	Escolhe o módulo pelo id da linha em gateways; valida ativação e credenciais.
Webhook	{Nome}Controller + PixWebhookProcessor	Autentica, deduplica e aplica o estado financeiro com as mesmas regras dos demais.
Painel	Admin → Adquirentes	Credenciais por ambiente, teste de conexão, ativar/desativar, auditoria e permissão própria.

PayGate

Item	Detalhe
Autenticação	HTTP Basic com key:secret, somente no servidor.
Ambientes	Sandbox (api-sandbox.paygate.com.br) e produção (api.paygate.com.br), com credenciais separadas.
PIX IN	POST /v1/gateway/request-qrcode (orderId, valor, expiração máx. 60 min); QR/copia-e-cola vem em pixHash (base64).
PIX OUT	POST /v1/gateway/request-cashout-pix; o orderId é a referência do saque, então repetir o pedido não paga duas vezes.
Status	GET /v1/transaction/{id}: PAID, WAITING/PENDING/CHECKING, CANCELED/ERROR, REFUND.
Webhook	POST /paygate/callbacks com X-Signature (HMAC-SHA256 do corpo) obrigatória.
Boleto e cartão	Não implementados: a documentação pública não traz endpoints.
Estorno	O PayGate oferece estorno, mas o SharkPay não tem fluxo de estorno; não foi ligado.

Garantias financeiras

Webhook não é confiável sozinho: após validar a assinatura, o estado e o valor são reconfirmados na API do PayGate antes de creditar ou concluir um saque.
Idempotência: um evento (transaction_id + status) é processado uma vez; falha transitória libera a chave para o PayGate reenviar.
Saque com resposta incerta (timeout, 5xx, orderId repetido): o saque permanece pendente com o saldo reservado, sem estorno e sem novo envio, até o webhook ou a conciliação (paygate:reconcile, a cada 10 min) decidir.
Subpagamento nunca confirma a cobrança.

Adicionar um novo adquirente

Inclua a definição em AcquirerRegistry (campos, ambientes, capacidades, limitações).
Crie a linha em gateways (migração), desativada por padrão.
Implemente o módulo em app/Lib/Pix/Banks (IPix; IPixReferenced se aceitar identificador próprio no saque). Classifique erros: definitivo (pode estornar) × ambíguo (lançar AmbiguousProviderException).
Registre o id na PixGateway.
Crie o webhook reutilizando PixWebhookProcessor (cashIn / cashOutConfirmed / cashOutFailed) e exclua a rota do CSRF.
Teste com Http::fake: criação, status, erros, ambiguidades, assinatura, replay, subpagamento e ausência de segredos em tela/log.

Teste antes de operar

Cadastre as credenciais de sandbox em Admin → Adquirentes → PayGate e use Testar conexão (consulta uma transação inexistente; não movimenta dinheiro).
Ative o ambiente de teste e escolha o PayGate como gateway padrão de cash-in/cash-out em Configurações.
Cadastre o webhook exibido na tela no painel do PayGate.
Gere uma cobrança de valor mínimo, pague no sandbox e confirme o webhook e a conciliação.
Só então cadastre as credenciais de produção, teste e ative com a confirmação explícita.