Troubleshooting

The card option is missing on Netcash's page#

Your amount is probably above your Pay Now transaction limit. New services start at R100, and above it Netcash hides the card option without an error. Test under R100, and ask your Netcash advisor to raise the limit.

Netcash notifications never arrive#

• Is the Notify URL set in NetConnector (Account profile → NetConnector → Pay Now)?
• Is it a public address? Netcash cannot reach localhost.
• Is there a ? in any of the four URLs? Remove it.
• Can you not see NetConnector? Ask your Netcash advisor to enable it for your user.

Netcash notifications arrive but nothing is marked paid#

Look at r.error and r.ignored from webhooks.handle:

• 503 gateway_down: Netcash's status check could not be reached. Netcash will notify again.
• reference mismatch: Netcash's status check is about a different reference.
• payment.mismatch event: Netcash confirmed a different amount than the payment.

Yoco events fail with signature_invalid#

• Is webhookSecret the whsec_ secret for this webhook? Each registered webhook has its own.
• Is the body reaching callCash untouched? In Express, use express.raw() on the webhook route, before any express.json().
• Is your server clock right? Events older than three minutes are refused.

Yoco events are ignored with "mode mismatch"#

A test event reached a live key, or the other way round. Check which key this deployment uses.

handle() returns handled: false#

The notification is not about a callCash payment. For Yoco, the event has no metadata.callcash. For Netcash, the reference is not one callCash issued. If older code opened that payment, pass the request on to it (see Webhooks).

My handler ran but the gateway keeps retrying#

Your handler threw. callCash answered 500 so the gateway retries, and the event comes back with redelivery: true. Fix the error; do not catch it and return 200.

reference_used when the customer tries again#

The reference was already paid, or is open for a different amount. Use a new reference per attempt at a different amount. A failed payment frees its reference.

config_invalid on start-up#

See the list on the Errors page. The most common: real gateways with no store, or a gateway in routes that is not in gateways.

"Cannot use import statement" or "require() of ES Module"#

The package is ESM only. Use import, or await import("callcash") from CommonJS.

It works locally, then forgets payments#

You are on the test gateway or MemoryStore, which keep everything in memory. Use a real store with real gateways.