Skip to main content

Handling Form Submissions

Customise how your Connected Payments payment form collects, validates, and processes submissions.

Before You Begin​

RequirementDetails
iFrame configurationAn active Connected Payments iFrame configuration (hosted or embedded)
Dashboard accessAccess to the Connected Payments admin dashboard
Google reCaptcha(Optional) Registered site key and secret key from google.com/recaptcha
PostMessage support(For external submit) Embedded iFrame integration
Code Sample Disclaimer

Code samples within this document are provided for reference purposes only and are not intended for production use.

How It Works​

  1. User fills form
  2. Optional: reCaptcha validation
  3. Optional: Confirmation step
  4. Form submitted
  5. Loading animation shown
  6. Display outcome in page OR redirect to merchant URL

Features Overview​

Google reCaptcha​

Protect your payment form against bots and automated attacks.

Supported: Hosted & Embedded

Setup steps:

  1. Register at google.com/recaptcha
  2. Add keys to admin dashboard
  3. Add reCaptcha component to form config

Google reCaptcha​

1. Register with Google​

Visit google.com/recaptcha to obtain:

KeyTypeUsage
Site KeyPublicClient-side (visible in form)
Secret KeyPrivateServer-side (stored in dashboard)

2. Add Keys to Dashboard​

Navigate to your iFrame configuration in the Connected Payments admin dashboard and enter both keys in the reCaptcha section.

3. Add Component to Form Config​

Add the reCaptcha component inside your form:

{
  "type": "form",
  "class": "payment-form",
  "children": [
    {
      "type": "reCaptcha",
      "theme": "light",
      "lang": "en"
    }
  ]
}

Confirmation Step​

Add a review screen between form submission and payment processing.

Configure in Dashboard​

In the Connected Payments admin dashboard, fill out the body of the confirmation section within the Customer Config.

Required Components​

ComponentPurpose
Confirm formForm with submit button to proceed
Edit form(Optional) Form with "formType": "editForm" to return to payment form

Flow​

External Submit Button​

Embedded iFrames Only

This feature is only available for embedded iFrame integrations with PostMessage support.

Trigger the payment form submission from a button on your merchant page instead of inside the iFrame.

How It Works​

Send a submit PostMessage to the iFrame's contentWindow. The iFrame validates all fields (including reCaptcha if enabled) before processing.

Implementation​

// Ref the iframe
const iframeRef = useRef(null);

const handleSubmit = () => {
  iframeRef.current.contentWindow.postMessage(
    JSON.stringify({ action: "submit" }),
    "https://sandbox.connectedpayments.commbank.com.au",
  );
};

return (
  <>
    <iframe ref={iframeRef} id="payment-iframe" src="YOUR_IFRAME_URL" />
    <button onClick={handleSubmit}>Complete Payment</button>
  </>
);

PostMessage Payload​

{ "action": "submit" }
Security

Always specify the exact target origin ("https://sandbox.connectedpayments.commbank.com.au") rather than "*" in production.

Best Practice

Only trigger submission when the iFrame form is valid. Monitor the isValid field in field interaction PostMessages to gate your submit button.

Loading Animations​

Customise the loading animation shown during payment processing to match your brand.

Setup​

Configure in the Connected Payments admin dashboard under your iFrame configuration's form submission loader settings.

Customisation Options​

OptionDescription
Animation typeChoose from available loading animation styles
ColorsMatch your brand palette
TextSet custom message (e.g. "Processing payment…")

Transaction Outcome Display​

Choose how the payment result is presented after processing completes.

Display Outcome in Payment Page​

Render the transaction result directly inside the iFrame using the response section of the Customer Config.

Available Variables​

VariableDescription
{txnReference}Transaction reference
{responseCode}Response code
{maskedPAN}Masked card number
{finalAmount}Final charged amount

Example Configuration​

{
  "tag": "div",
  "class": "success-message",
  "children": [
    { "tag": "h2", "text": "Payment Successful" },
    { "tag": "p", "text": "Reference: {txnReference}" },
    { "tag": "p", "text": "Card: {maskedPAN}" },
    { "tag": "p", "text": "Amount: ${finalAmount}" }
  ]
}