Skip to main content

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.

Icon
Before you begin

What you'll need:

  • configId - Your payment page configuration ID
  • userName - Your Connected Payments username with transaction permissions
  • secretKey - 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:

  1. Customer initiates checkout on your site
  2. Your server generates an HMAC-signed payment page URL
  3. 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)
  4. Customer enters payment details (card data never touches your server)
  5. Payment is processed through the payment network
  6. 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:

  1. Collect every parameter that will appear before verifyMessage in the payment page URL - including all required parameters and any optional parameters you want covered by the signature (for example, email, currency, metadata.*).
  2. Join each parameter as a key=value pair, separated by & - this is the query string you will send
  3. Hash the resulting string using HMAC-SHA256 with your secretKey
  4. Append the output as verifyMessage to your payment page URL
Sign every parameter

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.

Server-side only

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}`;
info

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:

  1. Payment is processed
  2. Connected Payments sends an HTTPS POST to your notification endpoint
  3. Your server validates the signature and processes the result
  4. 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​

MechanismPurposeApplies toValidation
PostMessageBrowser-side events for real-time UI updatesEmbedded iFrameOrigin check only
Notifications / Webhooks (optional)Server-to-server payment and status updatesEmbedded iFrame and Hosted PageSignature required

Approach:

  1. Combine as needed: use one or more mechanisms — they aren't mutually exclusive
  2. If you implement Notifications: treat them as the authoritative payment result
  3. Always: Validate signatures on Notifications
  4. Never: Process orders based solely on PostMessages

Step 5: Test integration​

Before moving to production, test the complete journey in Sandbox:

CheckWhat to verify
Successful paymentThe payment completes and your application records the result
Declined or failed paymentThe decline is shown to the customer and handled correctly
Error handlingInvalid requests and errors are handled gracefully
Embedded iFrame or Hosted PageThe payment page loads and behaves as expected for your chosen option
PostMessageEvents are received and handled, if implemented
Notifications / WebhooksNotifications 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.

ScenarioWhat happensWhen to use
Take payment onlyProcess the payment without tokenising the customer's cardYou only need to process the current payment
Let the customer choose to save their cardThe customer can choose whether their card is tokenised as part of the paymentYou want to offer a customer-facing Save card option for future use
Tokenise and take paymentProcess the payment and tokenise the card as part of the same payment flowYou 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=true to tokenise the card as part of the purchase. If you send it as a URL parameter, include it in the verifyMessage signature like every other parameter (see Step 1).
  • Customer controlled: expose tokenControl.token as 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.

note

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.

Need more information about creating, storing or using tokens?

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​

EnvironmentHosted Page URLEmbedded iFrame URL
Sandboxhttps://sandbox.connectedpayments.commbank.com.au/es-client-frontend/hostedhttps://sandbox.connectedpayments.commbank.com.au/es-client-frontend/embedded
Productionhttps://connectedpayments.commbank.com.au/es-client-frontend/hostedhttps://connectedpayments.commbank.com.au/es-client-frontend/embedded

Parameters​

ParameterTypeDescriptionExample
configIdstringYour payment page configuration ID. You can have multiple IDs for different use cases.'5f06c5f5-d4cb-483b-b0b2-242f48516dc5'
userNamestringConnected Payments username with transaction permissions'merchant.iframes'
txnTypeintegerTransaction type (see transaction types below)1
merchReferencestringUnique transaction reference — duplicates will be rejected'ORDER-12345'
amountstringAmount 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'
verifyMessagestringHMAC SHA-256 signature'abc123...'
info

For merchReference, use a format like ORDER-{orderId}-{timestamp} or a UUID to guarantee uniqueness.

Transaction types​

ValueTypeDescription
1PurchaseStandard payment
9CaptureCapture pre-authorized funds
10Pre-AuthHold funds without charging
20RefundRefund against original transaction
21Open RefundRefund without original transaction
30VoidCancel transaction before settlement
39ReversalReverse a transaction