Desenvolvedores

API, webhooks e integração

Use as chaves criadas pelo próprio merchant no painel. Nunca exponha a chave secreta no navegador.

Autenticação

No painel do merchant, acesse “Chaves de API”, crie uma credencial e guarde o segredo exibido uma única vez.

Authorization: Bearer sk_sua_chave_secreta
Accept: application/json
Content-Type: application/json
Idempotency-Key: pedido-123-tentativa-1

Em requisições POST de cobrança, use Idempotency-Key (8–190 caracteres). Repetir a mesma chave com o mesmo payload devolve a resposta original; reutilizar a chave com outro payload retorna conflito.

Criar cobrança

POST /api/v1/charges.php
{
  "provider": "asaas",
  "method": "pix",
  "amount": 149.90,
  "currency": "BRL",
  "name": "Cliente Exemplo",
  "email": "cliente@exemplo.com",
  "document": "00000000000",
  "description": "Pedido 123"
}

Providers disponíveis no pacote: efi, asaas, pagbank, mercadopago, stripe e crypto. Cartões usam checkout/tokenização hospedada pelo provedor; o backend não recebe PAN/CVV.

Consultar cobranças

GET /api/v1/charges.php
GET /api/v1/charges.php?id=123

Estornos

GET /api/v1/refunds.php
GET /api/v1/refunds.php?id=10
POST /api/v1/refunds.php
{
  "charge_id": 123,
  "amount": 49.90,
  "reason": "Solicitação do cliente"
}

Omitir amount solicita o restante elegível do estorno. O gateway precisa oferecer estorno para aquele método.

Clientes

GET /api/v1/customers.php
GET /api/v1/customers.php?id=123
POST /api/v1/customers.php
PUT /api/v1/customers.php?id=123
DELETE /api/v1/customers.php?id=123

Cadastre clientes reutilizáveis e envie customer_id ao criar uma cobrança.

Saldo

GET /api/v1/balance.php

Liquidações

GET /api/v1/settlements.php
GET /api/v1/settlements.php?id=15
POST /api/v1/settlements.php
{
  "amount": 1000,
  "currency": "BRL",
  "destination": {
    "bank": "Banco",
    "agency": "0001",
    "account": "12345-6",
    "holder": "Empresa Exemplo",
    "document": "00000000000100"
  }
}

A conta precisa estar ativa, aprovada em KYC/risco e com saldo disponível.

Links de pagamento

GET /api/v1/payment-links.php
GET /api/v1/payment-links.php?id=20
POST /api/v1/payment-links.php
PATCH /api/v1/payment-links.php?id=20
DELETE /api/v1/payment-links.php?id=20

Os links são hospedados no próprio sistema, podem ter valor fixo ou aberto, validade, URL de sucesso e métodos definidos pelo merchant.

Gerenciar webhooks via API

GET /api/v1/webhooks.php
POST /api/v1/webhooks.php
PATCH /api/v1/webhooks.php?id=7
DELETE /api/v1/webhooks.php?id=7

POST /api/v1/webhooks.php
{"action":"rotate","id":7}

Na criação ou rotação, o segredo é retornado uma única vez. URLs precisam ser HTTPS públicas; endereços privados e locais são recusados.

Webhooks enviados ao merchant

O sistema envia JSON com os cabeçalhos X-Fintech-Event, X-Fintech-Delivery e X-Fintech-Signature. Valide a assinatura usando HMAC-SHA256 do corpo bruto com o segredo do endpoint.

hash_hmac('sha256', $rawBody, $seuSegredo)

Eventos incluem criação/alteração de cobranças, estornos e ciclo de liquidação.

Webhooks recebidos dos provedores

Configure nos provedores as URLs públicas correspondentes:

/webhooks/efi.php
/webhooks/asaas.php
/webhooks/pagbank.php
/webhooks/mercadopago.php
/webhooks/stripe.php
/webhooks/crypto.php
/webhooks/didit.php

Para Efí Pix, a rota /webhooks/efi/pix também é aceita, pois o provedor pode acrescentar /pix à URL cadastrada.

Fila de entrega

Configure o cron da hospedagem para executar o worker regularmente:

php /caminho/do/sistema/bin/process-webhooks.php

Falhas são reenviadas com espera crescente e ficam visíveis nos painéis.

Produção

O instalador inicia com pagamentos em simulação. Configure HTTPS, SMTP, gateways, certificados, secrets de webhook e KYC; valide cada sandbox; depois desative “Pagamentos em modo simulação” no painel administrativo.