Guide

Webhooks

Some things happen after an API call returns — an ACH payment settles, a dispute is opened, or a merchant's onboarding status changes. Pay-Pi forwards signed events for these to a callback URL you register, so your systems stay in sync without polling.

What you'll receive

Pay-Pi forwards events including:

• ACH settlement — an ACH payment that was PENDING has settled or failed.
• Disputes — a payment has been disputed or charged back.
• Onboarding changes — a merchant's onboardingStatus, chargesEnabled, or payoutsEnabled changed.

Delivery

Each event is an HTTPS POST to your callback URL with a JSON body and a signature header. Events reference the affected object — for a payment, the same lcPaymentId and orderRef you saw when you created it.

POST https://your-app.example.com/webhooks/pay-pi
Content-Type: application/json
Pay-Pi-Signature: t=1718900000,v1=3f9a...   # verify before trusting the body

{
  "type": "payment.settled",
  "lcPaymentId": "pay_2Bd7...",
  "orderRef": "order-1042",
  "status": "SUCCEEDED",
  "finixTransferId": "TRa1Q...",
  "finixState": "SUCCEEDED"
}

Illustrative shape. The exact event types, field names, and signature header are listed in your dashboard when you configure your callback URL.

Verify the signature

Every request carries a signature derived from your webhook signing secret. Verify it against the raw request body before acting on an event, and reject anything that doesn't match — this is how you know the event genuinely came from Pay-Pi. Your callback URL and signing secret are configured from your dashboard.

Responding

Return a 2xx quickly to acknowledge receipt. Do the heavy work asynchronously, and make your handler idempotent (keyed on the event/payment id) so a retried delivery is safe to process twice.