Embedded iFrame - accept payments within your checkout
Embed the Connected Payments payment form within your website so customers can enter their payment details without leaving your checkout.
By the end of this guide, you'll have a working Embedded iFrame payment running in the Sandbox environment.
Before you start
You'll need:
configId— your iFrame configuration IDuserName— your Connected Payments username with transaction permissionssecretKey— your shared secret key used for HMAC generation- An HTTPS-enabled website
Generate signatures on your server. Never expose your secretKey in client-side code.
Your implementation journey
- Generate your payment request
- Build your Embedded payment URL
- Add the payment form to your checkout
- Handle payment messaging and responses
- Test a payment
Step 1 — Generate your payment request
Create the parameters for your payment request and generate the verifyMessage used by Connected Payments to validate the request.
Create your parameter string
Include every parameter that will appear before verifyMessage in the payment URL - the required parameters plus any optional ones you want covered by the signature.
const params = {
configId: "5f06c5f5-d4cb-483b-b0b2-242f48516dc5",
userName: "merchant.iframes",
txnType: 1,
merchReference: "ORDER-12345",
amount: "10.00", // dollars, not cents
};
const paramString = new URLSearchParams(params).toString();
The exact parameters included depend on the payment you're creating. See Parameters for the complete reference.
Generate verifyMessage
Generate an HMAC-SHA256 signature using your secretKey.
const verifyMessage = crypto
.createHmac("sha256", process.env.CONNECTED_PAYMENTS_SECRET_KEY)
.update(paramString)
.digest("hex");
Never generate verifyMessage in client-side code, because this would expose your secretKey.
Using another language? See the PHP, Python and C# examples.
Your server can generate a verifyMessage for your payment request.
Step 2 — Build your Embedded payment URL
Use your payment parameters and generated verifyMessage to construct the Embedded payment page URL.
const baseUrl =
"https://sandbox.connectedpayments.commbank.com.au/es-client-frontend/embedded";
const iframeUrl = `${baseUrl}?${paramString}&verifyMessage=${verifyMessage}`;
Your URL will follow this structure:
https://sandbox.connectedpayments.commbank.com.au/es-client-frontend/embedded
?configId=...
&userName=...
&txnType=...
&merchReference=...
&amount=...
&verifyMessage=...
Every URL parameter before verifyMessage must be included when generating verifyMessage, in the exact order it appears in the URL - not only the required ones. Add optional parameters to params before signing to have them verified - optional parameters added after verifyMessage are not signed or verified. Need another parameter? See Parameters.
Your server can generate a signed Embedded payment URL.
Step 3 — Add the payment form to your checkout
Use the generated URL as the source of an iFrame within your checkout page.
<iframe
id="connectedpayments-iframe"
src="YOUR_GENERATED_URL"
width="100%"
height="600px"
frameborder="0">
</iframe>
Open your checkout page in your browser. You should see the Connected Payments payment form displayed within your checkout.
The Connected Payments payment form loads successfully without navigating the customer away from your checkout.
Step 4 — Handle payment messaging and responses
Connected Payments provides mechanisms for your application to receive information about the payment experience and payment status. Depending on your implementation, you may use more than one mechanism.
PostMessage
Use PostMessage when your website needs to respond to browser-side events from the Embedded iFrame. For example:
window.addEventListener("message", (event) => {
// Validate the message origin
// Handle relevant Connected Payments events
});
Use these events to update the customer experience where required. See PostMessage events and payloads.
Notifications (optional)
Notifications provide server-to-server payment and status updates from Connected Payments. Use Notifications where your integration requires server-side payment status information or reconciliation. See Set up Notifications.
Your application handles the messaging and payment-response mechanisms required for your implementation.
Step 5 — Test a payment
Test the complete Embedded iFrame journey in Sandbox before moving to production.
| Scenario | Verify |
|---|---|
| Load checkout | Embedded payment form loads successfully |
| Successful payment | Successful payment is handled correctly |
| Declined payment | Decline is presented and handled correctly |
| Error scenario | Relevant error behaviour is handled |
| PostMessage | Events are handled correctly, if implemented |
| Notifications | Server-side updates are received correctly, if implemented |
See the Testing Guide for Sandbox credentials, test cards and detailed testing scenarios.
You can successfully complete and handle an end-to-end Sandbox payment.
Your Embedded iFrame integration is working
You've now:
- Generated and authenticated a payment request
- Built the Embedded payment URL
- Displayed the Connected Payments payment form within your checkout
- Implemented the relevant messaging and response handling
- Tested the payment journey in Sandbox