Migrating to IPN v2Copy Anchor Link

These instructions apply to the gateway release that includes the IPN format setting and durable delivery history. Upgrade the gateway and receiver together according to that release's notes. A pull request or an unpublished plugin archive is not a supported release.

Affected customers: sites using WooCommerce, aMember, or a custom IPN receiver.

Existing and new sitesCopy Anchor Link

Existing sites, including sites with no stored version, continue using signed IPN v1 after upgrade. New sites default to v2. You can explicitly select v1 when creating a site for an older integration.

Signed v1 remains supported through 30 June 2027. There is no automatic shutdown on that date. Removal requires a separately announced major release after customer migration and outstanding delivery work have been addressed.

Each notification uses one selected format. The gateway does not send both formats, negotiate with receivers, or downgrade after an error.

Upgrade and switchCopy Anchor Link

1. Upgrade the gateway to the matching main backend, Admin backend and frontend release before allowing v2 traffic. Use the normal controlled upgrade and traffic-drain procedure; arbitrary mixtures of older and newer producers are not supported.
2. Install the maintained WooCommerce plugin 1.2.0 or aMember plugin 1.2.0 once the corresponding release is published. Until publication, keep your currently supported release. Both compatible plugins accept signed v1 and v2.
3. For a custom receiver, implement signature validation, idempotency and ordering. IPN v2 is at least once: retries can repeat a notification, and different events can arrive out of order.
4. Verify a representative checkout on a test site. Where the receiver supports it, the optional readiness action can also check the callback from an existing checkout transaction.
5. Select v2 in Sites → Edit and save. Monitor delivery outcomes and your receiver's payment effects.

A readiness probe sends the signed ipn.test envelope without payment fields. A matching typed JSON response is required; a generic successful HTTP response is not proof of v2 support. WooCommerce supports this probe. The aMember endpoint does not yet support the probe; validate its normal checkout/payment lifecycle instead. The action needs an existing transaction from that site, never registers a new callback URL, and never changes the site's version.

Retries and callback URLsCopy Anchor Link

The gateway freezes a notification's version, destination, body and identity when accepting it. Changing the site or callback configuration does not rewrite queued notifications. Keep old checkout ipnUrl endpoints and their signing configuration available until their deliveries and manual replay obligations are settled. Retain compact ordering and payment-effect receipts beyond attempt-log retention, including for later manual replay.

Automatic v2 delivery has a maximum 48-hour retry window and an attempt limit of 20; the attempt limit can be reached earlier. V1 keeps its short three-attempt policy through the same durable queue: three total attempts with 1-second then 2-second delays and a two-minute automatic cycle, without v2 long retries. The v2 attempt limit often exhausts around 14 hours, before the 48-hour deadline. Authorized operators can retry an eligible failed delivery from transaction IPN history. Use the Transactions IPN needs attention filter to find unresolved exhausted/terminal deliveries or failed construction commands across historical transactions. A retry preserves the original body and delivery ID and uses a fresh signature. Failed construction commands are also visible and can be retried after their cause is corrected.

The transaction's aggregate ipnResponse remains available. Detailed attempt history is retained for 30 days, while the durable ordering and replay receipts survive that cleanup. Never delete receiver state to force a replay.

Rolling back a siteCopy Anchor Link

Selecting v1 again affects fresh checkouts. A checkout that has already accepted v2 delivery remains on v2 for subsequent events, including a payment event on another refund transaction for that checkout. Existing queued notifications retain their original format. Maintained receivers ignore delayed v1 notifications for an identity already using v2 to prevent older traffic from reversing newer state.

Do not downgrade the receiver to a version without v2 support while any v2 checkout or replay remains. Before downgrading gateway binaries, stop new work and drain durable deliveries and construction commands using the compatible release; older binaries cannot consume the new queue. Preserve the database and its replay receipts.

For migration help or an unresolved legacy integration, contact Payment Gateway App support.