Register and process gateway events
Connect a gateway receiver, verify deliveries, and recover safely from retries or uncertain payment outcomes.
Choose the gateway event contract
Gateway payment events use the gateway Webhooks settings and Webhook-Signature header. Merchant Sign-Up subscriptions use a separate signing contract. Keep their receivers or verification paths distinct. Gateway signature verification Merchant Sign-Up signature verification
Register your receiver
Prepare the receiver before enabling the subscription: delivery begins when the webhook is saved. Registration documented here is through the Merchant Portal; this guide does not invent a gateway subscription REST endpoint. Deploy a server endpoint that accepts POST over HTTPS with a valid TLS certificate. Preserve the request body bytes before JSON parsing. Open Settings → Webhooks in the Merchant Portal, choose Create, enter the receiver URL and select only the event types your application handles. Retrieve the signing key from Webhooks settings and keep it in server secret storage. Associate the receiver with the intended merchant environment. Save the webhook, then exercise the enabled event families with the provisioned test account. Record verified event IDs and observed outcomes without logging personal payment details. Documented gateway event catalog
Verify before applying a business change
Read t and s from Webhook-Signature. Compute HMAC-SHA256 with the gateway signing key over the nonce t, a literal period, and the unchanged request body. Compare the hexadecimal digest with s using a constant-time comparison. Only parse and act on a verified body. The source identifies t as a nonce; it does not document a timestamp-based expiry rule. webhook A valid signature authenticates the payload; it does not make repeated delivery safe. Store event_id and make business changes idempotent. Follow the local verification guide for the implementation and negative tests.
Accept durably, then acknowledge
Recommended receiver design: authenticate and validate the envelope, write a durable inbox record and return HTTP 200. A worker can process the accepted event separately. This is an application reliability pattern, not a gateway promise of exactly-once delivery. Validate event_id, event_type and the category-specific event_body after signature verification. Bind the merchant identity to an authorized tenant. Use a unique inbox key including the configured merchant/environment and event_id. Insert the inbox item and schedule processing atomically or through a transactional outbox. For an already accepted event, return HTTP 200 without repeating fulfillment, receipts or ledger changes. If durable acceptance fails, do not report success. Monitor the error and allow the gateway retry path to operate. Quarantine a verified but unsupported event type for investigation; acknowledge only after safely retaining it. Do not apply an unknown event to an order.
Understand delivery retries
The reviewed gateway retry policy requires HTTP 200. Other response codes trigger up to 20 reattempts over approximately three days, after which delivery stops. Early retries are closer together and later retries are farther apart. These timings can change; a backlog may reduce the number of attempts. Do not treat HTTP 202 or 204 as the documented acknowledgement. Keep gateway retry policy separate from the Merchant Sign-Up policy.
Handle uncertainty and ordering
The reviewed pages do not promise ordered delivery, a universal event timestamp, or an endpoint to replay missed gateway events. Treat events as notifications about a resource and reconcile when outcomes conflict. A transaction unknown result is not permission to submit the same payment again. Use transaction_id and the correct merchant context to investigate payment state; event_id identifies a notification, not a payment. Keep authorization, settlement and ACH return states distinct. A sale success event can still describe a transaction pending settlement. If a delayed event would undo a newer business state, retain it for audit and reconcile the resource instead of blindly overwriting state. After an outage, compare local orders and ledger entries against gateway transaction/reporting records. Alert on undelivered or unprocessed inbox items rather than relying only on retries. Retrieve a payment: current REST contract Query and reconciliation guide
Validate your receiver
Run these checks locally and then against a configured test merchant. Documentation review cannot prove delivery, processor availability or production routing. Test Expected application behavior Modified raw body or wrong key Reject verification; no business side effect. Same event delivered twice or concurrently One durable event and one business effect. Storage failure before acknowledgement No success acknowledgement; monitored failure. Valid event with unknown type Retain for investigation; do not fulfill an order. Delayed failure after a newer state Reconcile; preserve event history. Receiver outage and recovery Observe actual retries, drain queue and reconcile gaps.