Guides
Migrating an existing Netcash Pay Now integration
Move a Netcash Pay Now service to CentraPoint without breaking the payments your old system still creates, using legacy passthrough.
On this page
Why passthrough is needed#
Netcash Pay Now takes its Notify, Accept and Decline URLs from the service settings in the Netcash portal, not from each payment. A Pay Now service can therefore only notify one system. When you connect an existing service to CentraPoint, payments still created by your old integration (open carts, links already sent, other apps) would otherwise have their notifications and payer returns go to CentraPoint instead of your old system.
How passthrough works#
You give the old integration's payment references a recognisable prefix (for example SMX). When a notification or payer return arrives for a reference that starts with that prefix and that CentraPoint did not create:
- Notifications are forwarded to your old system's notify URL: the raw body with its original
Content-Type, viaPOST, retried after 1, 5, 15 and 60 minutes, 4 hours and 12 hours (7 attempts; 4xx responses other than 408 and 429 are not retried). CentraPoint acknowledges Netcash with200 OKonce queued. - Payer returns are redirected (303) to your old return URL with
TransactionAccepted,Reason,Reference,RequestTraceandExtra1–Extra3as query parameters.
A reference that matches a CentraPoint transaction is always processed by CentraPoint, even if it starts with the prefix. Forwarded notifications appear in the dashboard's Webhook log as Forwarded to legacy system.
1. Configure the gateway#
Under Settings → Payment providers → Netcash Pay Now, fill in the usual fields (service key, notify secret) and the legacy passthrough fields:
| Field | Key | Value |
|---|---|---|
| Legacy passthrough: reference prefix | passthroughPrefix | The start of every reference your old system uses, e.g. SMX. Matching is case-sensitive. |
| Legacy passthrough: notify URL (https) | passthroughNotifyUrl | Your old system's notification endpoint. Must be https on port 443 or 8443 with a public address. |
| Legacy passthrough: return URL (https) | passthroughReturnUrl | Where payers of old payments should land. Must be https. |
Leave the prefix empty to switch passthrough off.
2. Point the Netcash portal at CentraPoint#
In the Netcash portal, on the Pay Now service:
Notify URL: https://app.centrapoint.co.za/api/webhooks/netcash_paynow?provider=<providerId>&secret=<notifySecret>
Accept URL: https://app.centrapoint.co.za/api/payment/return
Decline URL: https://app.centrapoint.co.za/api/payment/return- Copy the notify URL with your provider ID from Settings → Payment providers and append the provider's notify secret. Notifications without the correct secret are neither processed nor forwarded.
- See the Netcash Pay Now gateway reference and Gateway notification URLs for details.
3. Adjust the legacy system#
- Make sure every reference it sends to Netcash starts with the prefix.
- Accept the forwarded notification at its notify URL exactly as it accepted Netcash's, and respond with a 2xx status.
4. Finish the migration#
- Create new payments through CentraPoint (payment links, invoices) instead of the old integration.
- Watch the Webhook log until no more forwarded notifications arrive for the old prefix.
- Clear the passthrough fields.