iFrame FAQs
Frequently asked questions about CommBank Connected Payments iFrame integration, terminology, and implementation.
Verify messages
What is a verify message?
A verify message is an HMAC-SHA256 value that authenticates your iFrame URL. It combines your URL parameters with your secret key to ensure the payment page hasn't been tampered with.
Verify Message = HMAC-SHA256(URL Parameters + Secret Key)
It is appended to the end of your iFrame URL.
How do I generate a verify message?
See How to Generate an iFrame URL for the full step-by-step guide.
- Collect all URL parameters in the correct order
- Concatenate them into a single string
- Apply HMAC-SHA256 using your secret key
- Append the hash to your URL
How do I keep my secret key secure?
- Store secret keys in environment variables or a secrets vault — never in client-side code
- Never commit secret keys to version control
- If a key is compromised, contact [email protected] immediately
- Rotate keys periodically as a security best practice
Hosted vs embedded iFrames
What is the difference between hosted and embedded iFrames?
| Hosted | Embedded | |
|---|---|---|
| How it works | Customer redirected to CommBank-hosted page | Payment form embedded in your page |
| User experience | Leaves your site temporarily | Never leaves your site |
| Development effort | Minimal | Requires iFrame + PostMessage handling |
| Best for | Fast implementation | Branded, seamless checkout |
How does a hosted iFrame work?
- Customer clicks Pay on your site
- Browser redirects to CommBank's hosted payment page
- Customer enters card details on CommBank's page
- Customer is redirected back to your site after payment
<a
href="https://connectedpayments.commbank.com.au/payment?amount=1000&ref=ORDER123&verify=abc123..."
>
Pay Now
</a>
How does an embedded iFrame work?
- The CommBank payment form loads inside an iFrame on your page
- Customer enters card details without leaving your site
- Payment processes within the embedded form
<iframe
src="https://connectedpayments.commbank.com.au/iframe?amount=1000&ref=ORDER123&verify=abc123..."
width="100%"
height="600"
frameborder="0"
>
</iframe>
Which iFrame type should I use?
Choose Hosted if you want the fastest implementation and are comfortable with customers briefly leaving your site.
Choose Embedded if you want a seamless, branded experience and can handle iFrame embedding and PostMessage events.
Referrers
What are referrers?
Referrers are a domain whitelist that controls which websites can render your iFrame. CommBank checks the referring domain on every request — if it isn't on your list, the iFrame is blocked.
This prevents unauthorised sites from embedding your payment form.
How do I set up referrers?
Email [email protected] with:
- Your iFrame config ID
- All domains to whitelist (include www, non-www, subdomains, and all TLDs)
- Target environment (sandbox or production)
Use HTTPS URLs only. Test in sandbox before applying to production.
Metadata
What is metadata?
Metadata is additional data you can attach to transactions for internal tracking, reporting, and analytics. It has no effect on payment processing.
Fields use the prefix metadata. followed by your chosen name (e.g. metadata.customerId).
What metadata fields are available?
| Field | Example | Use case |
|---|---|---|
metadata.customerId | CUST-12345 | Link to customer record |
metadata.orderId | ORD-98765 | Link to order |
metadata.country | AU | Geographic reporting |
metadata.browser | Chrome | Browser analytics |
metadata.browserVersion | 96.0 | Support diagnostics |
metadata.os | Windows | OS analytics |
metadata.deviceType | desktop | Device reporting |
metadata.language | en | Language preference |
metadata.campaignId | SUMMER2024 | Marketing attribution |
How do I add metadata to a request?
In iFrame URLs:
https://connectedpayments.commbank.com.au/iframe?amount=1000&ref=ORDER123&metadata.customerId=CUST-789&metadata.country=AU&verify=abc123...
In API requests:
{
"amount": 1000,
"merchReference": "ORDER123",
"metadata": {
"customerId": "CUST-789",
"country": "AU",
"deviceType": "mobile"
}
}
Can metadata appear in reports?
Yes. Contact [email protected] specifying which metadata fields you want as report columns — CommBank will configure them in your dashboard.
Transaction receipts
What are transaction receipts?
CommBank can automatically send email receipts to customers after approved transactions. Receipts include the transaction date, amount, masked card number, merchant reference, and receipt number.
Note: Email receipts are not tax invoices — they are confirmation of payment only.
How do I enable receipt emails?
Contact [email protected] with your iFrame config ID and the email address to use. Options:
- Static — always send to the same address
- Dynamic — pass the customer's email as a URL parameter
- Both — send to the customer and BCC an internal address
Receipts are sent for approved transactions only.
Troubleshooting
For a full troubleshooting reference, see the Troubleshooting Guide.
Common issues:
iFrame is not loading
See iFrame not loading in the Troubleshooting Guide.
"Invalid verify message" error
See Invalid verify message in the Troubleshooting Guide.
Metadata not appearing in reports
- Confirm the
metadata.prefix is included in field names - Check field names match what was configured with support
- Verify metadata is being included in the request payload
- Contact support to confirm custom reporting columns are enabled