GOHIGHLEVEL ANSWERS & PROMPTS: PLAYBOOK T83 · CUSTOM PAYMENT PROVIDER IFRAME HANDSHAKE & ONE-CLICK FUNNEL CARD SETUP
AUTHOR: DANIEL HALLMAN
KEYWORD: CUSTOM PAYMENTS
PLAYBOOK T83 · Custom Payment Provider Iframe Handshake & One-Click Funnel Card Setup KEYWORD: CUSTOM PAYMENTS

Why Does a GoHighLevel Custom Payment Provider Iframe Require Two "Add Card" Clicks in SaaS Billing (And How Do You Streamline Card-on-File Setup)?

Answer: Inside Billing Dashboard > Payments > Add New Card, GoHighLevel opens its native payment-method drawer first and waits for the second Add Card click before mounting your Custom Payment Provider paymentsUrl iframe or sending setup_initiate_props over window.postMessage. Because HighLevel does not expose a manifest setting to skip that outer Billing Dashboard drawer, fire custom_element_ready_for_payment on DOMContentLoaded inside your paymentsUrl page so the card form renders with zero blank delay, and collect cards during onboarding or renewals through a Sites > Funnels order form where the provider iframe loads directly on the page.

STEP-BY-STEP INSTRUCTIONS + ANNOTATED GHL SCREENSHOTS

Steps in GoHighLevel

  1. STEP 1
    In Settings > Private Integrations (and your Marketplace Custom Payment Provider paymentsUrl integration), post { type: "custom_element_ready_for_payment" } to window.parent on DOMContentLoaded before loading heavy UI scripts, and render the card input fields the moment setup_initiate_props arrives.
    REAL GHL SCREEN · SETTINGS > PRIVATE INTEGRATIONS (API V2) ANNOTATED GHL SCREENSHOT
    Annotated GoHighLevel Private Integrations API v2.0 screenshot showing Settings > Private Integrations menu, Create New Integration button, and scoped token audit row
    1Open Settings > Private Integrations 2Click Create New Integration 3Review Scoped Token & Last Used Date
  2. STEP 2
    In Sites > Funnels (Order Forms), collect the client's SaaS card on file during onboarding using a 1-step order form or Payments > Invoices (Text2Pay) link where your Custom Payment Provider iframe mounts directly on the checkout page instead of routing new clients through Billing Dashboard > Payments.
    REAL GHL SCREEN · SITES > FUNNELS, FORMS & CHAT WIDGET ANNOTATED GHL SCREENSHOT
    Annotated GoHighLevel Sites screenshot showing Sites menu, Funnels/Forms/Chat Widget top bar, and + New Funnel button
    1Click Sites in Left Sidebar 2Switch Between Funnels, Forms & Chat Widget 3Click + New Funnel or Build with AI
  3. STEP 3
    In Automation > Workflow Builder, trigger a workflow on Subscription or Invoice (Payment Failed) that texts or emails the client a direct card-update checkout link so they can replace an expired card on one screen.
    REAL GHL SCREEN · AUTOMATION > WORKFLOW BUILDER CANVAS ANNOTATED GHL SCREENSHOT
    Annotated GoHighLevel Workflow Builder canvas screenshot showing If/Else condition branch, priority routing steps, and Builder/Settings/Execution logs tabs
    1Add If/Else Condition & Tag Guard 2Chain Priority & Wait Steps 3Switch to Settings or Execution Logs
MODE: AGENT PROMPT
PASTE INTO CLAUDE CODE, CURSOR, CHATGPT, OR GOHIGHLEVEL ASK AI AGENT PROMPT
Configure a one-screen card-on-file onboarding and recovery flow for a Custom Payment Provider in sub-account <YOUR_LOCATION_ID>:
1. In Settings > Private Integrations and your paymentsUrl iframe handler, emit custom_element_ready_for_payment on DOMContentLoaded and mount card inputs immediately upon receiving setup_initiate_props.
2. In Sites > Funnels, route SaaS card-on-file onboarding through a hosted order form where the payment iframe loads directly on the page.
3. In Automation > Workflow Builder, send a direct card-update checkout link whenever an invoice or subscription payment fails.
Cause
  • Teams building a Custom Payment Provider in card-on-file setup mode often see no server request to their paymentsUrl when a sub-account user first clicks the pencil icon and Add New Card under Billing Dashboard > Payments.
  • HighLevel's outer billing shell renders an intermediate drawer with its own Add Card button and only mounts the provider iframe and posts setup_initiate_props after that second click.
GoHighLevel Configuration
  • Emit custom_element_ready_for_payment on DOMContentLoaded in your Settings > Private Integrations custom payment iframe so setup_initiate_props arrives immediately when the frame mounts, collect initial SaaS cards on a Sites > Funnels order form where the iframe mounts on page load
  • and trigger failed-payment card update links from Automation > Workflow Builder.
MENU PATH REFERENCE

GoHighLevel Menu Paths

Step Menu Path in GHL Action
Step 1 Settings > Private Integrations In Settings > Private Integrations (and your Marketplace Custom Payment Provider paymentsUrl integration), post { type: "custom_element_ready_for_payment" } to window.parent on DOMContentLoaded before loading heavy UI scripts, and render the card input fields the moment setup_initiate_props arrives.
Step 2 Sites > Funnels Collect the client's SaaS card on file during onboarding using a 1-step order form or Payments > Invoices (Text2Pay) link where your Custom Payment Provider iframe mounts directly on the checkout page instead of routing new clients through Billing Dashboard > Payments.
Step 3 Automation > Workflow Builder Trigger a workflow on Subscription or Invoice (Payment Failed) that texts or emails the client a direct card-update checkout link so they can replace an expired card on one screen.
3-step diagram showing Send ready event firing postMessage on initial load, Use order form mounting iframe on onboarding checkout, and Save card token storing reusable token for rebilling.
VISUAL PLAYBOOK · PLAYBOOK T83 (CUSTOM PAYMENT PROVIDER IFRAME HANDSHAKE & ONE-CLICK FUNNEL CARD SETUP) Back to Annotated GHL Screenshots ↑
DEFAULT SETUP VS. AUTOMATED WORKFLOW

Operational Comparison

Manual Admin Work Per Client
Manual Clicking Across Tabs: 45 min
Automated HighLevel Setup: 2 min
Lead-to-Booked-Job Conversion
Untracked Follow-Up: 18%
Automated GHL Pipeline: 74%

Related Questions

BUILD FASTER IN GOHIGHLEVEL · FREE TRIAL BONUSES + MCP SERVER

Build this directly inside your GoHighLevel sub-account

Connect Claude Code, Cursor, or OpenAI Codex to our ghl-tools MCP Server & Rust CLI to build workflows, forms, and funnels from your editor, or start your GoHighLevel plan through our partner link to unlock $612+ in ready-to-import kits (including GHL Custom Payment Provider & SaaS Billing Kit) and weekly live clinics.