Subscribing
You don't subscribe to webhooks in an admin panel — you pass your URL on each payment request:
webhook_url— called when the payment reaches a final state.webhook_url_transaction— called at the gateway-level payment stage (for flows that expose the intermediate step).
Pass HTTPS URLs. A plain HTTP endpoint is accepted but strongly discouraged — the webhook carries transaction state you want signed and encrypted in transit.
Payload
Webhooks arrive as JSON. A typical payload looks like:
{
"transaction_id": "txn_123456789",
"reference_number": "INV-2025-001",
"status": "completed",
"amount": "150.00",
"currency": "GBP",
"timestamp": "2026-04-23T10:30:00Z"
}Status values: completed, failed, cancelled, timeout. Amount fields are decimal strings, matching what you sent on the original request. Currency and country codes are ISO.
Security
Your endpoint should do three things before trusting a webhook body:
- Confirm the request came from a Paytia-announced IP range. Request the current list from support — it's versioned alongside platform releases.
- Verify the signature header. Sign-and-verify is rolling out to new tenants — see your onboarding doc for the current shared-secret signing approach.
- Only use HTTPS. A webhook over HTTP is trivially spoofable. We'll stop sending to HTTP-only endpoints in a future platform release.
Retries
If your endpoint returns anything other than a 2xx, Paytia retries with exponential backoff — 1 minute, 5 minutes, 30 minutes, then hourly up to 24 hours. That gives your system plenty of time to recover without needing a manual resend.
Retries reuse the same transaction_id. Your handler must be idempotent — check whether you've already processed this ID before acting on it. Idempotency is the single most common webhook integration mistake.
Testing
For local development, any request-inspector service works well — webhook.site gives you a unique URL that captures the full body. Point webhook_url at it, run a sandbox transaction, and watch the webhook arrive in your browser. Every flow page in these docs has a try-it explorer so you can fire one now.
Failed deliveries
After the full retry schedule, Paytia stops sending and marks the webhook delivery failed. You can pull the final state via a reconciliation endpoint, or the support team can replay individual webhooks from the platform admin UI.
Error codes returned by your endpoint are captured and visible on request. Paytia-side error codes →