Skip to main content

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 ID
  • userName — your Connected Payments username with transaction permissions
  • secretKey — your shared secret key used for HMAC generation
  • An HTTPS-enabled website
Security

Generate signatures on your server. Never expose your secretKey in client-side code.

Your implementation journey​

  1. Generate your payment request
  2. Build your Embedded payment URL
  3. Add the payment form to your checkout
  4. Handle payment messaging and responses
  5. 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");
Server-side only

Never generate verifyMessage in client-side code, because this would expose your secretKey.

Using another language? See the PHP, Python and C# examples.

Checkpoint

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=...
Important

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.

Checkpoint

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.

Checkpoint

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.

Checkpoint

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.

ScenarioVerify
Load checkoutEmbedded payment form loads successfully
Successful paymentSuccessful payment is handled correctly
Declined paymentDecline is presented and handled correctly
Error scenarioRelevant error behaviour is handled
PostMessageEvents are handled correctly, if implemented
NotificationsServer-side updates are received correctly, if implemented

See the Testing Guide for Sandbox credentials, test cards and detailed testing scenarios.

Checkpoint

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

Next steps​