Embedded and Hosted Integration Guide
This guide explains how to integrate the Connected Payments payment page into your checkout using either an Embedded iFrame or Hosted Page experience. Follow the steps below to authenticate your request, generate the payment page URL, present the payment experience, handle responses and test your integration.
What you'll need:
configId- Your payment page configuration IDuserName- Your Connected Payments username with transaction permissionssecretKey- Your shared secret key (for HMAC generation)- HTTPS-enabled website (for Embedded iFrames)
Code samples: Code samples within this document are provided for reference purposes only and are not intended for production use.
How it works
Flow:
- Customer initiates checkout on your site
- Your server generates an HMAC-signed payment page URL
- Connected Payments validates the signature and referrer, and renders the payment page — within your checkout (Embedded iFrame) or as a page the browser navigates to (Hosted Page)
- Customer enters payment details (card data never touches your server)
- Payment is processed through the payment network
- The result is sent to your server as a Notification (webhook, optional), and returned to the customer by PostMessage, as applicable
How to integrate
Embedded iFrame and Hosted Page follow the same integration journey. The implementation only differs at Step 3, where you choose how to present the payment page.
Jump to: Step 1 · Step 2 · Step 3 · Step 4 · Step 5
Step 1: Authenticate request
Generate HMAC signature
Every payment request requires a verifyMessage — an HMAC-SHA256 signature that proves the URL was created by your server and hasn't been tampered with. Connected Payments validates this on every request.
How to generate it:
- Collect every parameter that will appear before
verifyMessagein the payment page URL - including all required parameters and any optional parameters you want covered by the signature (for example,email,currency,metadata.*). - Join each parameter as a
key=valuepair, separated by&- this is the query string you will send - Hash the resulting string using HMAC-SHA256 with your
secretKey - Append the output as
verifyMessageto your payment page URL
Include all parameters before verifyMessage in the signature, in the exact order they appear in the URL.
Optional parameters added after verifyMessage are not signed or verified.
Sign the URL-encoded values exactly as sent, including spaces and special characters.
Never generate the verifyMessage in client-side code — doing so would expose your secretKey. Always perform this step on your server.
Node.js
const crypto = require("crypto");
// Every parameter placed before verifyMessage in the URL (required + any optional), in URL order
const params = {
configId: "5f06c5f5-d4cb-483b-b0b2-242f48516dc5",
userName: "merchant.iframes",
txnType: 1,
merchReference: "ORDER-12345",
amount: "10.00", // dollars, not cents
};
// Create parameter string from all parameters
const paramString = new URLSearchParams(params).toString();
// Generate HMAC
const verifyMessage = crypto
.createHmac("sha256", process.env.CONNECTED_PAYMENTS_SECRET_KEY)
.update(paramString)
.digest("hex");
PHP
$params = [
'configId' => '5f06c5f5-d4cb-483b-b0b2-242f48516dc5',
'userName' => 'merchant.iframes',
'txnType' => 1,
'merchReference' => 'ORDER-12345',
'amount' => '10.00' // dollars, not cents
];
// Signs every parameter in $params
$paramString = http_build_query($params);
$verifyMessage = hash_hmac('sha256', $paramString, getenv('CONNECTED_PAYMENTS_SECRET_KEY'));
Python
import hmac
import hashlib
import os
from urllib.parse import urlencode
params = {
'configId': '5f06c5f5-d4cb-483b-b0b2-242f48516dc5',
'userName': 'merchant.iframes',
'txnType': 1,
'merchReference': 'ORDER-12345',
'amount': '10.00' # dollars, not cents
}
# Signs every parameter in params
param_string = urlencode(params)
verify_message = hmac.new(
os.getenv('CONNECTED_PAYMENTS_SECRET_KEY').encode(),
param_string.encode(),
hashlib.sha256
).hexdigest()
C#
using System.Security.Cryptography;
using System.Text;
// Include every parameter placed before verifyMessage in the URL (required + any optional), in URL order
string paramString = "configId=5f06c5f5-d4cb-483b-b0b2-242f48516dc5&userName=merchant.iframes&txnType=1&merchReference=ORDER-12345&amount=10.00";
using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("CONNECTED_PAYMENTS_SECRET_KEY"))))
{
byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(paramString));
string verifyMessage = BitConverter.ToString(hash).Replace("-", "").ToLower();
}
For the authentication methods used by the Connected Payments APIs, see the API Authentication Guide.
Step 2: Build payment page URL
Append the parameter string and verifyMessage to the Hosted Page or Embedded iFrame endpoint using a ?.
const baseUrl =
"https://sandbox.connectedpayments.commbank.com.au/es-client-frontend/hosted";
const paymentPageUrl = `${baseUrl}?${paramString}&verifyMessage=${verifyMessage}`;
Your assembled URL will look like this for a Hosted Page:
https://sandbox.connectedpayments.commbank.com.au/es-client-frontend/hosted?configId=5f06c5f5-d4cb-483b-b0b2-242f48516dc5&userName=merchant.iframes&txnType=1&merchReference=ORDER-12345&amount=10.00&verifyMessage=abc123def456...
Your assembled URL will look like this for an Embedded iFrame:
https://sandbox.connectedpayments.commbank.com.au/es-client-frontend/embedded?configId=5f06c5f5-d4cb-483b-b0b2-242f48516dc5&userName=merchant.iframes&txnType=1&merchReference=ORDER-12345&amount=10.00&verifyMessage=abc123def456...
For the Production endpoints, see Environments. For all supported parameters, see Parameters.
Step 3: Present payment page
Embedded iFrame and Hosted Page share the rest of the integration journey. Choose how to present the payment page to your customers:
Option A: Embedded iFrame
Embed the Connected Payments payment page within your website, so customers pay without leaving your checkout. Use the /embedded endpoint.
<iframe
id="connectedpayments-iframe"
src="YOUR_GENERATED_URL"
width="100%"
height="600px"
frameborder="0"
allow="payment"
>
</iframe>
Option B: Hosted Page
Redirect the customer to the Connected Payments hosted payment page. Use the /hosted endpoint.
window.location.href = paymentPageUrl;
Step 4: Handle messaging & responses
Connected Payments provides different mechanisms for communicating payment events and outcomes. Depending on your integration requirements, you may use one or more of these mechanisms. These options are not mutually exclusive.
PostMessage
Browser-side messaging and events (Embedded iFrame). Listen for real-time updates from the iFrame. Use them for UI feedback — never as authoritative payment confirmation.
Benefits:
- Real-time updates and field-level validation feedback
- Immediate user experience feedback
Limitations:
- Dependent on customer's browser
- Can be blocked by browser settings
- Not suitable as authoritative source
View PostMessage implementation example
window.addEventListener("message", (event) => {
// Validate origin
if (event.origin !== "https://sandbox.connectedpayments.commbank.com.au") {
return;
}
const message = event.data;
if (message.info === "Payment outcome for the transaction") {
if (message.responseCode === "00") {
showSuccess(message.txnReference);
} else {
showError(message.responseText);
}
}
});
For all events and payloads, see the PostMessages Guide.
Notifications / Webhooks (optional)
Server-to-server payment and status updates (Embedded iFrame and Hosted Page). Notifications are optional. When implemented, they provide reliable, authoritative payment results to your server.
How it works:
- Payment is processed
- Connected Payments sends an HTTPS POST to your notification endpoint
- Your server validates the signature and processes the result
- Your server responds with HTTP 200 to acknowledge receipt
View webhook implementation example
app.post("/webhook", express.json(), (req, res) => {
// 1. Validate signature
const signature = req.headers["x-signature"];
if (!isValidSignature(req.body, signature)) {
return res.status(401).end();
}
// 2. Process payment result
const { responseCode, merchReference, txnReference } = req.body;
if (responseCode === "00") {
// Payment successful
fulfillOrder(merchReference);
sendConfirmationEmail(merchReference);
} else {
// Payment failed
notifyCustomer(merchReference, "Payment declined");
}
// 3. Acknowledge receipt (must return 200)
res.status(200).send("OK");
});
Configuration: Notifications are configured in your payment page configuration. Contact CommBank Support to set up. For setup, payloads and retries, see the Notifications Guide.
Response handling comparison
| Mechanism | Purpose | Applies to | Validation |
|---|---|---|---|
| PostMessage | Browser-side events for real-time UI updates | Embedded iFrame | Origin check only |
| Notifications / Webhooks (optional) | Server-to-server payment and status updates | Embedded iFrame and Hosted Page | Signature required |
Approach:
- Combine as needed: use one or more mechanisms — they aren't mutually exclusive
- If you implement Notifications: treat them as the authoritative payment result
- Always: Validate signatures on Notifications
- Never: Process orders based solely on PostMessages
Step 5: Test integration
Before moving to production, test the complete journey in Sandbox:
| Check | What to verify |
|---|---|
| Successful payment | The payment completes and your application records the result |
| Declined or failed payment | The decline is shown to the customer and handled correctly |
| Error handling | Invalid requests and errors are handled gracefully |
| Embedded iFrame or Hosted Page | The payment page loads and behaves as expected for your chosen option |
| PostMessage | Events are received and handled, if implemented |
| Notifications / Webhooks | Notifications are received, validated and acknowledged, if implemented |
For test credentials, test cards, and detailed testing scenarios, see the Testing Guide.
Optional: Tokenise cards during payment
Choose how you want to handle card tokenisation
Depending on your payment experience, you can choose whether to tokenise a customer's card when they make a payment. This applies to both the Embedded iFrame and the Hosted Page.
| Scenario | What happens | When to use |
|---|---|---|
| Take payment only | Process the payment without tokenising the customer's card | You only need to process the current payment |
| Let the customer choose to save their card | The customer can choose whether their card is tokenised as part of the payment | You want to offer a customer-facing Save card option for future use |
| Tokenise and take payment | Process the payment and tokenise the card as part of the same payment flow | You need both the payment and a token for future use |
Let the customer choose to save their card
You can add a checkbox or toggle to the payment page that allows the customer to choose whether their card is tokenised during payment.
Map the control to tokenControl.token:
- Merchant controlled: set
tokenControl.token=trueto tokenise the card as part of the purchase. If you send it as a URL parameter, include it in theverifyMessagesignature like every other parameter (see Step 1). - Customer controlled: expose
tokenControl.tokenas a checkbox or toggle to let the customer choose whether to save their card. For a customer-facing experience, use a clear label such as Save card.
Example payment page configuration:
{
"children": [
{
"type": "checkbox",
"class": "input-checkbox",
"value": "false",
"valid": "true",
"disabled": false,
"name": "tokenControl.token",
"mapTo": "tokenControl.token",
"readonly": false
},
{
"class": "checkbox-label",
"tag": "label",
"text": "Save card"
}
],
"tag": "div",
"class": "field-group-row"
}
Add this to your payment page configuration in the Merchant Portal. See Customise your Payment Page.
This example shows how to expose tokenisation as a customer choice. If you do not need to offer card tokenisation, you can continue to process the payment without this control.
See the Tokenisation Integration Guide.
Complete example
View full Node.js implementation
// server.js
const express = require("express");
const crypto = require("crypto");
const app = express();
const CONFIG = {
configId: "5f06c5f5-d4cb-483b-b0b2-242f48516dc5",
userName: "merchant.iframes",
secretKey: process.env.CONNECTED_PAYMENTS_SECRET_KEY,
// Use /hosted to redirect to a Hosted Page, or /embedded to display an Embedded iFrame
baseUrl:
"https://sandbox.connectedpayments.commbank.com.au/es-client-frontend/hosted",
};
function generateIframeUrl(orderData) {
const params = {
configId: CONFIG.configId,
userName: CONFIG.userName,
txnType: 1,
merchReference: orderData.reference,
amount: orderData.amount,
};
// Add optional parameters before signing
if (orderData.email) params.email = orderData.email;
// Create parameter string (every parameter placed before verifyMessage, in URL order)
const paramString = new URLSearchParams(params).toString();
// Generate HMAC
const verifyMessage = crypto
.createHmac("sha256", CONFIG.secretKey)
.update(paramString)
.digest("hex");
// Build complete URL
return `${CONFIG.baseUrl}?${paramString}&verifyMessage=${verifyMessage}`;
}
// Payment page
app.get("/checkout/:orderId", async (req, res) => {
const order = await getOrder(req.params.orderId);
const iframeUrl = generateIframeUrl({
reference: `ORDER-${order.id}-${Date.now()}`,
amount: order.total.toFixed(2), // dollars, e.g. "10.00"
email: order.customerEmail,
});
res.render("checkout", { iframeUrl });
});
// Webhook handler
app.post("/webhook", express.json(), (req, res) => {
if (!validateSignature(req.body, req.headers["x-signature"])) {
return res.status(401).send("Invalid signature");
}
if (req.body.responseCode === "00") {
updateOrder(req.body.merchReference, "paid");
fulfillOrder(req.body.merchReference);
} else {
updateOrder(req.body.merchReference, "failed");
}
res.status(200).send("OK");
});
app.listen(3000);
View full PHP implementation
<?php
function generateIframeUrl($orderData) {
$config = [
'configId' => '5f06c5f5-d4cb-483b-b0b2-242f48516dc5',
'userName' => 'merchant.iframes',
'secretKey' => getenv('CONNECTED_PAYMENTS_SECRET_KEY'),
'baseUrl' => 'https://sandbox.connectedpayments.commbank.com.au/es-client-frontend/hosted'
];
$params = [
'configId' => $config['configId'],
'userName' => $config['userName'],
'txnType' => 1,
'merchReference' => $orderData['reference'],
'amount' => $orderData['amount']
];
// Add optional parameters before signing
if (!empty($orderData['email'])) {
$params['email'] = $orderData['email'];
}
$paramString = http_build_query($params);
$verifyMessage = hash_hmac('sha256', $paramString, $config['secretKey']);
$params['verifyMessage'] = $verifyMessage;
return $config['baseUrl'] . '?' . http_build_query($params);
}
$order = getOrder($_GET['orderId']);
$iframeUrl = generateIframeUrl([
'reference' => 'ORDER-' . $order['id'] . '-' . time(),
'amount' => number_format($order['total'], 2, '.', ''), // dollars, e.g. "10.00"
'email' => $order['email']
]);
?>
<!DOCTYPE html>
<html>
<body>
<iframe src="<?php echo htmlspecialchars($iframeUrl); ?>" width="100%" height="600px"></iframe>
</body>
</html>
View full Python implementation
import hmac
import hashlib
import time
from urllib.parse import urlencode
from flask import Flask, render_template
import os
app = Flask(__name__)
CONFIG = {
'config_id': '5f06c5f5-d4cb-483b-b0b2-242f48516dc5',
'user_name': 'merchant.iframes',
'secret_key': os.getenv('CONNECTED_PAYMENTS_SECRET_KEY'),
'base_url': 'https://sandbox.connectedpayments.commbank.com.au/es-client-frontend/hosted'
}
def generate_iframe_url(order_data):
params = {
'configId': CONFIG['config_id'],
'userName': CONFIG['user_name'],
'txnType': 1,
'merchReference': order_data['reference'],
'amount': order_data['amount']
}
# Add optional parameters before signing
if order_data.get('email'):
params['email'] = order_data['email']
param_string = urlencode(params)
verify_message = hmac.new(
CONFIG['secret_key'].encode(),
param_string.encode(),
hashlib.sha256
).hexdigest()
return f"{CONFIG['base_url']}?{param_string}&verifyMessage={verify_message}"
@app.route('/checkout/<order_id>')
def checkout(order_id):
order = get_order(order_id)
iframe_url = generate_iframe_url({
'reference': f'ORDER-{order["id"]}-{int(time.time())}',
'amount': f"{order['total']:.2f}", # dollars, e.g. "10.00"
'email': order['email']
})
return render_template('checkout.html', iframe_url=iframe_url)
Configuration reference
Environments
| Environment | Hosted Page URL | Embedded iFrame URL |
|---|---|---|
| Sandbox | https://sandbox.connectedpayments.commbank.com.au/es-client-frontend/hosted | https://sandbox.connectedpayments.commbank.com.au/es-client-frontend/embedded |
| Production | https://connectedpayments.commbank.com.au/es-client-frontend/hosted | https://connectedpayments.commbank.com.au/es-client-frontend/embedded |
Parameters
- Required
- Optional
- Platform Partners
| Parameter | Type | Description | Example |
|---|---|---|---|
configId | string | Your payment page configuration ID. You can have multiple IDs for different use cases. | '5f06c5f5-d4cb-483b-b0b2-242f48516dc5' |
userName | string | Connected Payments username with transaction permissions | 'merchant.iframes' |
txnType | integer | Transaction type (see transaction types below) | 1 |
merchReference | string | Unique transaction reference — duplicates will be rejected | 'ORDER-12345' |
amount | string | Amount in dollars with two decimal places (e.g. 10.00 = $10.00, 1.01 = $1.01). Do not send cents - 101 is charged as $101.00 | '10.00' |
verifyMessage | string | HMAC SHA-256 signature | 'abc123...' |
For merchReference, use a format like ORDER-{orderId}-{timestamp} or a UUID to guarantee uniqueness.
| Parameter | Type | Description | Default |
|---|---|---|---|
currency | string | 3-letter currency code | 'AUD' |
email | string | Customer email address (mandatory when using 3DSecure) | - |
channel | string | The transactional channel for the transaction. Character limit of 200. | 'iframe' |
cardToken | string | Pre-existing token for saved cards | - |
tokenControl.token | boolean | Controls whether the card is tokenised as part of the payment flow. See Tokenise cards during payment | false |
onlyTokenise | boolean | Create a token without charging the card. 3DS is not supported for token-only requests. | false |
metadata.* | string | Custom metadata passed as individual query parameters, each prefixed with metadata. (e.g. metadata.customerId=CUST-789) | - |
As part of integrating with Connected Payments, platforms are required to identify themselves by providing a Platform name in the Channel field during connection or configuration.
The Channel field is used to indicate the originating platform or plug‑in (for example RMS, Xetta, or Nelnet) and is recorded against the connection. This value is then associated with all transactions initiated via that connection to support visibility across the Connected Payments ecosystem.
This requirement applies to all Connected Payments platform integrations.
| Parameter | Type | Description | Example |
|---|---|---|---|
channel | string | Captures the platform name used to connect to Connected Payments. This value identifies the originating platform and is stored against the associated transaction to support platform visibility, reporting and operational support. | 'Platform Name' |
Transaction types
| Value | Type | Description |
|---|---|---|
1 | Purchase | Standard payment |
9 | Capture | Capture pre-authorized funds |
10 | Pre-Auth | Hold funds without charging |
20 | Refund | Refund against original transaction |
21 | Open Refund | Refund without original transaction |
30 | Void | Cancel transaction before settlement |
39 | Reversal | Reverse a transaction |