Skip to main content
This page is for teams building operationally correct Pagou integrations.

​
Core rule

Use webhooks as the source of truth for asynchronous status transitions. Polling is only a fallback.

​
Minimum handler contract

  1. Receive HTTPS POST events.
  2. Acknowledge fast with 200 OK.
  3. Deduplicate by event ID.
  4. Process asynchronously.
  5. Reconcile uncertain states with a GET call.
app.post("/webhooks/pagou", async (req, reply) => {
	const event = req.body as { id: string };

	reply.code(200).send({ received: true });

	if (await alreadyProcessed(event.id)) {
		return;
	}

	await queue.push(event);
});

​
Event families

  • Transaction events: payment lifecycle for Pix and cards
  • Transfer events: payout lifecycle for Pix Out

​
Continue with