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.
| Campo | Descrição |
|---|
status | pending, delivered, failed |
retry_count | Número de tentativas realizadas |
next_retry_at | Próxima tentativa agendada (ISO 8601) |
Seu endpoint deve retornar 2xx em até 10 segundos. Respostas fora desse intervalo são tratadas como falha e entram na fila de retenção.
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}
