Skip to main content
Webhooks serve as the core real-time notification mechanism for your financial integration. Instead of making repetitive API requests (polling) to check payment states, compliance verifications, or dispute status, Pagsmile pushes signed HTTP POST requests directly to your backend as soon as events occur.

Instant Value Delivery

Trigger immediate fulfillment or balance credits the moment a Pix payment is confirmed.

Infra Efficiency

Eliminate redundant API polling, drastically reducing infrastructure overhead and network load.

Automated Operations

Handle MED disputes and KYB compliance updates automatically via background workers.

​
Event Families

Pagsmile categorizes webhooks into three primary domain families:

Pix Transactions

Financial settlement notifications for inbound/outbound payments and refunds (PIX_PAYMENT_IN, PIX_PAYMENT_OUT, PIX_REFUND_IN, PIX_REFUND_OUT)Scope: ACCOUNT or USER

KYB Compliance

Status updates for compliance sessions on Virtual and Master accounts (VA_ACCOUNT_KYB, MASTER_ACCOUNT_KYB).Scope: PLATFORM (Master) / USER (Virtual)

MED Processing

Lifecycle events for Special Refund Mechanisms (MED_CASE_*, INFRACTION_*).Scope: USER or ACCOUNT

​
Webhook Provisioning

Where and how to configure your subscriptions depend on the event family:
Programmatically subscribe to transaction and KYB events using numeric IDs[cite: 1]:
  • 1 — PIX_PAYMENT_IN[cite: 1]
  • 2 — PIX_PAYMENT_OUT[cite: 1]
  • 3 — PIX_REFUND_IN[cite: 1]
  • 4 — PIX_REFUND_OUT[cite: 1]
  • 5 — VA_ACCOUNT_KYB[cite: 1]
  • 6 — MASTER_ACCOUNT_KYB[cite: 1]

​
Receiver Checklist

1

Expose a Stable URL

Use a permanent HTTPS endpoint. Do not rely on HTTP redirects.
2

Capture Raw Bytes

Read and retain the exact raw request body in memory before parsing JSON for signature verification.
3

Validate Headers

Verify both X-Content-Hash and X-Signature before processing the JSON payload.
4

Enforce Idempotency

Persist the event using its documented idempotency key (delivery_id or txn_id + event type).
5

Acknowledge Fast

Return an explicit HTTP 200 status code immediately upon accepting the payload.