Goal

Let marketplace vendors connect their own Stripe account from inside the app, so the site can pay their commissions with Stripe transfers. End state: the vendor’s WooCommerce Product Vendors record carries a Stripe account id and stripe_approved = true.

Before you start

• Recipe: Initial Stripe setup is done (the platform keys are saved).
• WooCommerce Product Vendors and MAM WooCommerce Product Vendors are active, and your vendors exist as Product Vendors terms with vendor-admin users.
• Gravity Forms and the MAM forms integration are active (the enrollment form is a Gravity Form).
• The MAM notification system is set up (the enrollment link is delivered by email).

One-time site setup

1. Create and bind the enrollment form

Create a Gravity Form with two fields: the vendor’s company name and company email. Then, on the MAM Gravity Forms settings screen, bind it under Setup Stripe Link, mapping the Company Name and Company Email fields. (This stores the form id and field map in the mam_stripe_send_link / …_email / …_company options.)

Add the form to the app (e.g. as a left-menu item) like any other MAM form. Once a vendor has a connected Stripe account, the plugin removes that menu item from their app automatically.

Binding the form also enables an hourly cron job, “Stripe fetch all approved vendors”, which scans your connected Stripe accounts and flips each vendor’s stripe_approved flag when Stripe enables payouts for them.

2. Publish the return page

Create a WordPress page containing the shortcode:

[mam_stripe_connect_return]

Just saving the page registers it — the plugin detects the shortcode on save and records the page as the canonical onboarding return target (option mam_stripe_connect_return_page_id). No other configuration is needed. (Only if no such page exists does the Stripe Connect Return URL fallback setting apply.)

What the vendor experiences

1. Enrollment form. The vendor opens the form in the app. Their email (and company name, when the site knows exactly one for them) is pre-filled. They submit.
2. Account creation. The plugin creates a Stripe Connect account (type standard; country defaults to US — filterable via mam_stripe_connect_account_country) for that email. Re-submitting never creates a duplicate: the email→account mapping is remembered.
3. Email link. The vendor receives the “Stripe – Seller Enrollment” notification email containing their personal onboarding link (enrollment_link replacement). The link is a Stripe-hosted AccountLink, protected by a one-time state token valid for 1 hour and bound to the user who started the flow.
4. Stripe onboarding. The vendor completes Stripe’s own identity/bank forms on stripe.com.
5. Return page. Stripe sends them back to your [mam_stripe_connect_return] page. The page requires login, validates the state token (same user who started the flow), saves the Stripe account id onto the vendor record, and shows one of:
   • Success — charges and payouts enabled; the vendor is marked approved.
   • Pending — Stripe still needs information; the page lists what’s due and offers a Continue Stripe Setup button with a fresh onboarding link.
   • Error — expired/mismatched session, with instructions to connect again.

Expired links and the refresh flow

Stripe AccountLinks are short-lived. If a vendor clicks an expired link, Stripe redirects them to the plugin’s refresh handler (admin-ajax.php?action=refresh_stripe_connect), which issues a fresh onboarding link and forwards them straight back into Stripe onboarding. Security rules (all deny-by-default):

• With a live state token, the session simply resumes — request parameters are ignored in favor of the server-side token payload.
• With no/expired token, a new session is only created when the supplied vendor/account pair matches what the site already knows: the account stored on that vendor, or (first onboarding) an account this site created. Filter: mam_stripe_can_refresh_connect.
• Store managers (manage_woocommerce, filter mam_stripe_user_can_manage) may always refresh.
• The browser is only ever redirected to https://stripe.com / *.stripe.com URLs (filter mam_stripe_allowed_redirect).

Checking vendor status

• Vendor record: the Product Vendors term meta / taxonomy_{vendor_id}_metas option carries stripe_account_id (acct_…), stripe_approved, and any stripe_requirements_due.
• The hourly “Stripe fetch all approved vendors” scan keeps stripe_approved current even when the vendor finishes onboarding days later without revisiting the return page. It can also be run on demand by a store manager (admin-ajax action mam_stripe_approved_vendors).

Related articles

• Recipe: Initial Stripe setup
• Recipe: Payout flow and reconciliation
• Hook: mam_stripe_approved_vendors
• Hooks: Stripe security filters

Metadata