Troubleshooting Guide

Quick reference for diagnosing and resolving common issues across all Connected Payments integrations and the dashboard.

---

Quick reference

Symptom	Area	Jump to
401 Unauthorized	API / Authentication	Authentication errors
403 Forbidden	API / Permissions	Authentication errors
429 Too Many Requests	API / Rate limiting	Rate limiting
500 Internal Server Error	API / Server	API errors
iFrame not loading / blank	iFrame	iFrame not loading
400 Bad Request on iFrame	iFrame	400 Bad Request
iFrame fields won't click	iFrame	Unclickable iFrame
"Invalid verify message" error	iFrame / HMAC	Invalid verify message
Batch file rejected	Batch Processing	Batch file rejected
Batch transactions failing	Batch Processing	Batch transactions failing
Webhooks / notifications not arriving	Notifications	Notification issues
Notifications retrying constantly	Notifications	Notification issues
Password reset email not received	Dashboard	Password reset issues
Cannot create user	Dashboard	User management issues
User cannot log in	Dashboard	User management issues
Reconciliation discrepancy	Reporting	Reconciliation issues
Transaction timed out	Timeouts	Timeout handling
401 / 400 / 403 during tokenisation setup	Tokenisation	Tokenisation errors
SSL or connection error on tokenisation requests	Tokenisation	Tokenisation errors

---

Authentication errors

401 Unauthorized

Cause: Invalid or missing API credentials.

Check	Action
Authorization header present	Ensure Authorization: Bearer <key> is included on every request
Correct key for environment	Sandbox and production keys are separate — verify you are using the right one
Key not revoked	Generate a new key from the dashboard under Settings → API Keys if the key was deleted or expired
userName/password correct	For username and password auth, confirm credentials match your dashboard account exactly
Bearer prefix included	The header value must be Bearer <key>, not just <key>

tip

Never expose API keys in client-side code or version control. Use environment variables and rotate keys regularly.

403 Forbidden

Cause: Valid credentials, but the user does not have permission for the requested operation.

Check	Action
Correct role assigned	Ensure the user has the appropriate role (e.g. API Transaction Role for payment APIs)
Account is active	Confirm the user account has not been deactivated
Refund permissions	Refund requests require the Matched Terminal role in addition to Virtual Terminal
Endpoint access	Verify the endpoint is available under your account configuration

For full role details, see the User Roles overview.

---

Rate limiting

429 Too Many Requests

Cause: Your integration has exceeded the allowed request rate for your account.

Solution	Detail
Implement exponential backoff	Wait and retry with increasing delays on each failed request
Cache responses	Avoid sending repeated identical requests in a short window
Batch requests	Combine multiple operations where the API supports it
Contact support	Contact Support to discuss rate limit increases

---

API errors

500 Internal Server Error

Cause: A temporary issue on the Connected Payments platform.

1. Check the status page for any active incidents
2. Retry the request using exponential backoff
3. If the issue persists, Contact Support with the error details and request ID

Request timeout / no response

Cause: No response was received within the 60-second timeout window.

1. Increase your client-side timeout to at least 60 seconds if it is set lower
2. Check your network connectivity
3. Retry as a new transaction — the platform automatically attempts to void timed-out transactions to prevent double charges

warning

Do not treat a timeout as a confirmed decline. Always check the transaction status in the dashboard before retrying a payment with the customer.

---

iFrame integration

iFrame not loading

Blank / not loading

First, open the browser developer console:

• Chrome / Edge / Firefox: F12 → Console tab
• Safari: Preferences → Advanced → Show Develop menu, then Cmd+Option+C

Red text in the console indicates an error. Copy the full message when contacting support.

Likely cause	Fix
verifyMessage is incorrect	Recalculate — ensure parameters are sorted A–Z and all are included
Config ID is wrong	Confirm configId matches your iFrame configuration exactly
iFrame URL uses HTTP	iFrame URLs must use HTTPS

Testing without an embed

Switch from embed to hosted in your URL to test your parameters without needing to embed the iFrame:

https://connectedpayments.commbank.com.au/payment/hosted?...

This isolates parameter issues from referrer/embed issues. A 400 in hosted mode still indicates a parameter or verifyMessage problem.

500 Server Error

Cause: Connected Payments service is temporarily unavailable.

1. Check the Connected Payments Status Page
2. Wait a few minutes and retry
3. Contact Support if the issue persists

---

400 Bad Request

Cause: Incorrect verifyMessage, wrong parameter values, or mismatched parameter names.

Parameters must be sorted alphabetically and all included in the HMAC calculation.

Common mistake	Correct value
amount=100.00	amount=10000 (cents, no decimal point)
currency=aud	currency=AUD (uppercase)
username=...	userName=... (camelCase)
external_reference=...	externalReference=...
Parameters not sorted	Parameters sorted A–Z
Missing a parameter	All parameters included

info

A 400 error in hosted mode still indicates a parameter or verifyMessage issue — not an embed problem.

---

Invalid verify message

Error: "Invalid verify message" or "verifyMessage is invalid"

Check	Action
Correct secret key	Confirm the key matches the one configured in your iFrame settings
Parameter order	Must be sorted A–Z, matching the documentation exactly
No extra whitespace	Remove any leading/trailing spaces or line breaks from parameter values
Correct hashing algorithm	Must use SHA-256, not SHA-1 or MD5
URL encoding	Ensure URL encoding is applied correctly to any special characters in parameter values

---

Unclickable iFrame

Symptom: The iFrame renders but form fields, buttons, or links do not respond to clicks — particularly common on mobile.

Cause: Another element is overlapping the iFrame.

How to find it:

1. Right-click the iFrame → Inspect
2. In DevTools, check the iFrame's z-index and position
3. Look for sibling or parent elements with a higher z-index, or absolutely positioned overlays

Fix with CSS:

/* Give the iFrame a high z-index */
iframe#paymentFrame {
  position: relative;
  z-index: 1000;
  width: 100%;
  height: 600px;
}

/* Ensure overlays sit below it */
.modal-overlay,
.site-header {
  z-index: 999;
}

/* Mobile-specific fix */
@media (max-width: 768px) {
  iframe#paymentFrame {
    position: relative;
    z-index: 1000;
    min-height: 500px;
  }
}

---

iFrame pre-support checklist

Before contacting support, confirm the following:

• Browser console checked for errors
• verifyMessage calculation verified (parameters sorted A–Z, all included)
• Parameter names and values confirmed (case-sensitive)
• Tested in hosted mode to isolate embed vs. parameter issues
• Overlapping elements checked
• Browser cache cleared

When contacting Support, include:

• Screenshot of the full console error
• Complete iFrame URL (remove your shared secret)
• Browser name and version
• Steps to reproduce the issue
• Your iFrame configuration name

---

Batch processing

Batch file rejected

Cause: The uploaded file does not meet the naming or format requirements. Files that fail validation are rejected before any transactions are processed.

Cause	Fix
Filename already used	Change the suffix to a new unique value — filenames cannot be reused
Date is in the past	Use today's date or a future date
Wrong file extension	File must end in .csv
Wrong SFTP directory	Confirm the upload path with Connected Payments support

Correct filename format: [customerID]-[yyyymmdd]-[suffix].csv

info

The suffix must be unique per customer. Use a value such as recurring-{timestamp} or batch-{date}-{run} to guarantee uniqueness.

---

Batch transactions failing

Cause: Individual transaction rows contain invalid or missing data.

Cause	Fix
Invalid hashedUserName	Re-check the HMAC-SHA256 calculation — confirm the shared secret is correct
Duplicate merchReference	Every row must have a unique merchant reference value
Amount not in cents	10000 = $100.00 — do not include a decimal point
Missing txnId on refund or complete	Include the original transaction ID from the initial purchase
Both pan and cardToken provided	Provide one or the other, not both

tip

Test in your sandbox SFTP environment before submitting live batches. See the Testing Guide for sandbox test cards and tokens.

---

Notifications

Notification delivery issues

Not receiving notifications

Check	Action
Endpoint is publicly reachable	Verify the URL is accessible from the internet over HTTPS
Firewall rules	Allow inbound traffic from Connected Payments notification IPs — resolve current addresses using nslookup notifications.connectedpayments.commbank.com.au (production) or nslookup simulation-notifications.connectedpayments.commbank.com.au (sandbox)
Endpoint returns 200 OK	Any non-200 response or timeout is treated as a failure and triggers a retry
Notification rule is active	Confirm the rule is configured and enabled in the dashboard

Endpoint keeps retrying

Cause: Your endpoint is not returning HTTP 200 OK.

Respond with 200 OK as soon as the notification is received — before any heavy processing:

app.post("/notifications", async (req, res) => {
  res.status(200).json({ success: true }); // Acknowledge first
  await processNotification(req.body); // Process after responding
});

Issue	Cause	Fix
Retries keep coming	Not returning 200	Return 200 immediately on receipt
Notifications arriving late	Previous attempt timed out	Reduce endpoint response time; acknowledge before processing
Duplicate notifications processed	No idempotency check	Track processed txnReference values and skip duplicates
All retries exhausted, no email	No email on the rule	Add an emails array to the notification rule configuration

Authentication failing

Cause: The custom header secret does not match what is configured on the notification rule.

• Confirm the header name and value match exactly what was set in the notification rule
• Store the secret in an environment variable — never hardcode it
• Check for any extra whitespace in the secret value

Retry schedule

Notifications retry on a Fibonacci backoff schedule (1 min, 1 min, 2 min, 3 min, 5 min...) capped at 15-minute intervals. See Notification Re-Attempts for the full schedule and recommended maxAttempt values.

---

Dashboard

Password reset issues

Not receiving reset email

1. Check your spam/junk folder
2. Wait a few minutes — email delivery may be delayed
3. Verify your registered email address is correct

If still not receiving:

• Contact your IT team to whitelist [email protected]
• Ask them to check email filtering rules and gateway settings

Reset link expired

Reset links expire after 24 hours.

1. Return to the login page
2. Click Forgot Password?
3. Request a new reset link
4. Use the new link promptly

Password requirements error

Error: "Password does not meet requirements"

Your password must meet all of the following:

Requirement	Detail
Minimum length	At least 16 characters
Numbers	At least 1 number (0-9)
Uppercase	At least 1 uppercase letter (A-Z)
Special characters	At least 1 special character

Common mistakes: password too short, missing uppercase letter or number, using a disallowed special character.

Temporary password expired

New users whose temporary password has expired (after 3 days) cannot use password reset.

1. Contact your user admin
2. Admin deletes and recreates the user account
3. Check email for the new temporary password
4. Log in and set a permanent password within 3 days

danger

API users whose passwords have been reset will fail all requests immediately — update any integrations using the old password before resetting.

---

User management issues

Cannot create user

Cause	Fix
Insufficient permissions	Verify you are logged in as an Admin Manager with the Dashboard Admin role
Customer ID incorrect	Customer ID is case-sensitive — open your profile to copy it exactly (e.g. CCP, not ccp)
Username already exists	Choose a different username; usernames cannot be reused

User cannot log in

Cause	Fix
Temporary password expired (>3 days)	Recreate the user account — password reset will not work for expired temporary passwords
User is deactivated	Edit the user in Admin Settings and set status to Active
Incorrect username or password	Use Forgot Password? on the login page to reset
Roles not applied correctly	Edit the user, reselect required roles, click Save, then ask the user to log out and back in

---

Reconciliation issues

Discrepancy between Connected Payments report and bank settlement

Pre-contact checklist

Work through these checks before contacting support:

• Connected Payments report date range matches the bank settlement period exactly
• All hierarchies are included in the report
• Settlement timing accounted for (T+1 or T+2 depending on your acquirer)
• Reviewed transactions with high-risk error codes: 91, 99, 799, 790
• Checked the Status Page for any outages during the settlement period

High-risk error codes

The following response codes indicate transactions that may have processed at the bank but appear as declined in Connected Payments:

Code	Description	Reconciliation risk
91	Card issuer unavailable	High — may have processed despite showing declined
99	System error / timeout	High — transaction status uncertain
799	Unknown error	Very High — often processes despite showing declined
790	Processing error	Medium — status needs verification

danger

Error codes 91, 99, 799, and 790 are the most common source of reconciliation discrepancies. Always investigate these before finalising a reconciliation run.

Contacting support

If a discrepancy remains after your checks, Contact Support with:

• Variance amount
• Settlement period and date
• Report filters used (include a screenshot)
• Transaction IDs associated with high-risk error codes
• Bank settlement statement (attached)

See the Reconciliation Discrepancy Guide for a full email template and the support resolution process.

---

Timeout handling

All transactions have a 60-second timeout window. When the platform does not receive a valid response within this window, it records the transaction with one of the following response codes:

Code	Description
99	Standard timeout
797	Downstream network unavailable
798	Unknown downstream error (timeout-like)
799	Unknown error (timeout-like)

What the platform does automatically

1. The timed-out transaction is added to a timeout queue
2. The platform queries the downstream gateway and submits a void to prevent double charges
3. Retries continue until the settlement date passes, attempts are exhausted, or the transaction is confirmed as declined or voided

info

You do not need to take any action for the platform to process timeouts. You can treat the transaction as requiring verification and retry as a new transaction once the status is confirmed.

What you should do

warning

Never assume a timed-out transaction is declined. Check the transaction status in the dashboard before retrying a payment with the customer.

• Check the dashboard for the final transaction status before taking any action
• Retry only after confirming the original transaction did not process
• Watch for response codes 91, 99, 797-799 in reconciliation — these are the most common source of settlement discrepancies

---

Tokenisation errors

Error	Likely cause	Fix
401 Unauthorized	Wrong credentials or password case mismatch	Double-check username and password — passwords are case-sensitive
400 Bad Request	Restricted character in a field, or missing required field	Remove special characters; check all required fields are present
403 Forbidden	Wrong environment URL	Confirm you are pointing to sandbox vs production correctly
SSL / connection error	Request sent over HTTP	Switch all requests to HTTPS

info

Tokenisation uses the same userName and password credentials as your dashboard account. If you receive a 403, check that your user has the API Token Role assigned. See User Roles overview for role details.