Overview

PayGrid POSTs signed JSON to your server when a payment status changes. Use webhooks as your primary integration path; poll GET /api/v1/payments/{id} only as a fallback.

​

You only need webhook_url

callback_url is optional. The API does not require either URL on payment create, but for a working integration you should set webhook_url (per payment or as a merchant default). If callback_url is omitted or empty, PayGrid simply skips callback delivery — no error, no failed payment. Set only webhook_url unless you have a specific reason for a second, simpler endpoint (see below).

​

Webhook vs callback

Both use the same HMAC signing. Use webhook_url for almost every integration. It delivers lifecycle events (payment.completed, payment.failed, …) and is sufficient to fulfill orders, cancel on failure, and track status. Add callback_url only if you want a separate, one-shot POST with a flatter JSON body when a payment reaches a terminal status — for example a legacy fulfillment service that expects type: "transaction.callback" instead of webhook events. For mobile payments, the first webhook is usually already the terminal event (payment.completed or payment.failed), so a callback rarely adds value.

​

Integration path

Follow these steps in order:

1. Obtain your webhook signing key — separate from your API key and API secret. See Verify signatures.
2. Configure your endpoint URL — per payment or as a merchant default. See Setup.
3. Build your handler with signature verification — verify the raw request body before parsing JSON. See Verify signatures.
4. Process events idempotently — deduplicate, validate, and update your order state. See Handle events.
5. Test end-to-end — dashboard test webhook, then a live payment. See Setup → Testing.

​

What to expect

• No webhook at payment creation. pending is the initial state; webhooks fire on transitions only.
• The first webhook you receive is usually the first transition (often straight to a terminal status like completed or failed).
• There is no payment.pending event. Payout events use the same {type}.{status} pattern (e.g. payout.completed). See Payload reference for event names and JSON shapes.

Next step: Setup your webhook URL