Webhooks

A PlugToPay entrega notificações assíncronas para a URL configurada na sua empresa sempre que o status de uma transação muda.

Configuração

Defina a URL de destino via painel (Orquestração → Configuração de request) ou via API:

PUT /api/v1/user/company/config
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "webhook_url": "https://seusite.com/webhooks/plugtopay"
}

Payload

O backend envia um POST para a URL configurada com o PaymentResource completo da transação:

{
  "status": "approved",
  "transaction_id": "019ddb56-fbe3-72e1-9f3c-8d0b2faf8f73",
  "amount": 15000,
  "payment_method": "card",
  "attempts": 1,
  "created_at": "2026-04-30T01:23:45+00:00",
  "updated_at": "2026-04-30T01:23:46+00:00",
  "transactions": [ ... ],
  "card": { ... }
}

Retentativas

A PlugToPay reprocessa webhooks com falha automaticamente via WebhookRetryCron. Cada tentativa fica registrada com retry_count e next_retry_at. Você pode acompanhar o status de entrega no detalhe de cada transação no painel.

Callbacks de gateway (inbound)

Além dos webhooks de saída para o merchant, a PlugToPay recebe callbacks dos próprios gateways em:

POST /api/v1/webhooks/{gateway}

Esse endpoint é público (sem autenticação) e é usado pelos gateways para notificar mudanças de status assíncronas (ex: PIX confirmado). Você não deve chamar este endpoint diretamente.