Server-to-Server Notifications

📘

Your account must eb enabled for this feature

IPG can send your application a server-to-server transaction notification after it processes a payment. The capability is not limited to IPG Connect: IPG sends these notifications from the applicable submission component when a transaction reaches a reportable result, including asynchronous result updates for supported payment methods.

The notification is an asynchronous HTTP request from IPG to your server. It is independent of a customer's browser redirect, so use it to update order state rather than treating a success or failure URL as the final payment confirmation.

How it works

1. Configure a transaction notification URL for the store or through the configuration mechanism provided by the submission component. Connect can also accept transactionNotificationURL in the payment request when the store is enabled to override configured URLs.
2. IPG processes the transaction and sends the notification when a result is available. Some alternative payment methods can first report WAITING and later send an updated result.
3. IPG sends an asynchronous POST to the configured URL with form URL-encoded fields (application/x-www-form-urlencoded).
4. Your endpoint validates notification_hash, records the event idempotently, updates the order from the verified result, and returns a successful HTTP response promptly.

The customer's return to responseSuccessURL or responseFailureURL is a browser navigation and can be abandoned, replayed, or manipulated. Never ship goods or mark an order paid solely because the customer reached a return URL.

Configure the notification URL

Configure the store-level Transaction Notification URL in your IPG administration or store-management integration. The equivalent property is transactionNotificationUrl. This store configuration is used by submission components that support the common transaction-notification flow.

For IPG Connect integrations that are enabled for per-request URL overrides, send this field with the payment request:

transactionNotificationURL=https://merchant.example.com/payments/ipg/notifications

Use a stable, publicly reachable HTTPS endpoint. Do not use an endpoint that requires an interactive login, browser cookies, CSRF validation, or a customer session. If the endpoint changes, update the store configuration before directing live payments to the new endpoint.

Recurring payments have a separate store configuration, recurringTransactionNotificationUrl. Use it when recurring-payment notifications are enabled for the store.

Notification request

IPG sends a form URL-encoded HTTP POST. A representative notification is:

POST /payments/ipg/notifications HTTP/1.1
Host: merchant.example.com
Content-Type: application/x-www-form-urlencoded

ipgTransactionId=1234567890&oid=ORDER-100045&chargetotal=49.99&currency=978&txndatetime=2026:09:10-15:30:45&storename=12345678901&approval_code=Y:123456:...&status=APPROVED&hash_algorithm=SHA256&notification_hash=...

The exact field set varies by transaction type, payment method, and enabled services. Your receiver must accept additional fields and must not reject a valid notification merely because it contains fields it does not use.

Depending on the payment method, IPG can also include processor, funding, masked-card, token, mandate, bank-account, or scheme-specific fields. Treat these as optional. Do not log sensitive values unnecessarily, and never expect a full PAN or CVV in a notification.

Validate the notification

Before changing order state, validate notification_hash using the shared secret configured for the same store and transaction origin. Use a constant-time comparison. The common notification flow uses the following hash contract; consult the submission component's integration guide for any component-specific variation.

For current HMAC-capable algorithms, the signed values are, in this order:

chargetotal | currency | txndatetime | storename | approval_code

storename is the IPG store ID. Generate the HMAC using the indicated hash_algorithm and your shared secret, then compare the result with notification_hash. The separator shown above is part of the current HMAC representation; do not add spaces or substitute the merchant order ID.

Some established integrations use legacy hash algorithms with a legacy concatenation format. Keep the validation implementation aligned with the algorithm selected for your Connect integration. When migrating an existing integration, validate test notifications with the configured algorithm before switching live traffic. Do not accept a notification when the hash is missing, cannot be calculated, or does not match.

Receiver requirements

Implement the receiver as a small, durable ingestion endpoint:

1. Accept POST form fields and preserve the raw parameter values needed to validate the hash.
2. Look up the expected store and shared secret from trusted server-side configuration, not from a customer browser or request-supplied secret.
3. Verify notification_hash before any business-side state change.
4. De-duplicate by ipgTransactionId; an endpoint should tolerate the same notification more than once.
5. Apply state transitions safely. In particular, do not replace a terminal approved result with an older or less final result.
6. Persist the verified event and its processing outcome before acknowledging it. Keep enough masked diagnostic data to investigate disputes.
7. Return a 2xx response as soon as the notification is durably accepted. Queue slow fulfilment, email, and downstream work rather than delaying the HTTP response.

IPG delivers the notification asynchronously and can retry delivery after a transport failure or server error. Delivery has no exactly-once guarantee, so your receiver must be idempotent. Return a 5xx response only when retry is appropriate; a 4xx response is suitable for a notification that is permanently invalid.

Result handling

Use the verified notification to drive order state:

The final business decision must use the verified status and applicable transaction type. For example, an authorization, capture, refund, or void must update the corresponding payment operation, not simply a generic order-paid flag.

Example receiver pseudocode

on POST /payments/ipg/notifications:
    fields = parseFormUrlEncodedBody(request)
    storeId = fields["storename"]
    secret = configuredSecretFor(storeId, trustedTransactionOrigin)

    expectedHash = createNotificationHash(
        secret,
        fields["hash_algorithm"],
        fields["chargetotal"],
        fields["currency"],
        fields["txndatetime"],
        storeId,
        fields["approval_code"]
    )

    if !constantTimeEquals(expectedHash, fields["notification_hash"]):
        recordRejectedNotification(fields)
        return 400

    eventId = fields["ipgTransactionId"]
    if alreadyProcessed(eventId):
        return 204

    persistAndApplyVerifiedPaymentUpdate(eventId, fields)
    enqueueAnySlowFollowUpWork(eventId)
    return 204

Test checklist

• Configure a non-production notification endpoint for the test store.
• Test approved, failed, and, where applicable, waiting-to-final payment flows.
• Confirm that the receiver rejects an altered notification_hash and does not change the order.
• Re-submit a valid notification and confirm it does not create duplicate payments, fulfilments, or emails.
• Confirm the endpoint responds quickly while slow downstream work continues asynchronously.
• Verify that application logs and monitoring mask payment and personal data.