billing help · For platform operators
Platform account guides
Letting workspaces connect their own provider accounts without copying keys: the Stripe Connect platform, the PayPal partner application, the Square OAuth application, the Authorize.net referral, and the sandbox checklist.
- Connected accounts: how they work
- Stripe Connect platform
- PayPal partner application
- Square OAuth application
- Authorize.net referral and Solution ID
- Sandbox checklist for connected accounts
Connected accounts: how they work
A workspace can reach its provider account in two ways:
- Own keys — the owner copies API keys into a credential set and registers a webhook. This is how every set worked before version 1.1.
- Connected account — the owner signs in at the provider and allows this platform's application to take payments for the account. No keys are copied and the workspace registers no webhook.
Either way the money goes to the workspace's own provider account. The platform adds no fee and never holds the funds.
Platform applications#
Super → Platform apps holds the platform's own application at each provider, one per provider and environment (Test, Live):
| Provider | What the application is | Guide |
|---|---|---|
| Stripe | A Stripe account with Connect enabled | Stripe Connect |
| PayPal | A REST app approved as a partner (Multiparty) | PayPal partner |
| Square | An OAuth application | Square OAuth |
| Authorize.net | A referral link and a Solution ID — not a connection | Authorize.net referral |
An application goes Draft → Verified. Workspaces are offered the connection when the application is verified and its webhook value is saved; without the webhook, payments on connected accounts would never be confirmed. Disabled stops every connected set that depends on the application.
Changing a key returns the application to Draft until it is verified again. Sets that are already connected use the new key at once — there is only one key — so change keys at a quiet time and verify straight away.
Statuses of a connection#
Text description
A connected set starts as Onboarding while the workspace fills in the provider's own pages. When the provider knows the account but does not accept payments on it yet, the set is Restricted. When the provider accepts payments the set is Enabled and goes into service as Test or Live. An enabled account can become restricted again, which takes the set out of service and e-mails the owners. From any of the three the connection can end as Revoked: the workspace disconnects, or the provider reports that access was withdrawn. Revoked is final.
The status always comes from the provider. It is asked when the owner returns from the provider's pages, when the provider reports a change to the platform endpoint, when someone presses Check status now, and by the hourly job connect.sync (waiting sets every hour for 30 days, sets in service once a day).
| Connection | Set status | Meaning |
|---|---|---|
| Onboarding | Draft | The provider's pages have not been completed |
| Restricted | Draft | The provider knows the account but does not accept payments on it yet |
| Enabled | Test or Live | In service |
| Revoked | Disabled | Ended, by the workspace or at the provider. Final for this set |
A set that was in service and stops being Enabled is taken out of service at once and the workspace's owners are e-mailed. It returns on its own when the provider accepts payments again. A person can also disable a set for a while without ending the connection.
Platform webhook endpoints#
Each application has one endpoint, shown on its page:
/webhooks/<provider>-platform.php?app=<application id>
Events of every connected account arrive there. The signature is checked with the application's own secret before anything is read; the event is then matched to the credential set by the account it names and handled exactly like a delivery to a workspace's own endpoint. The application's page lists the latest deliveries and what was done with each. unrouted means the event named an account no set is connected to.
What protects a connection#
- Stripe — the platform creates the account and stores its id before anyone is redirected.
- PayPal — PayPal is asked which seller completed the sign-up that carries the set's tracking id. The seller id in the return address is ignored: anybody can type an address.
- Square — a single-use value, valid 30 minutes, bound to the signed-in member and the set, must come back with the authorization.
- One provider account serves one set on the whole platform at a time.
- Square access tokens are stored encrypted like keys, renewed weekly, and erased when the connection ends.
- Only workspaces that manage their own gateways can connect (a workspace whose gateways the platform manages is not offered it), and only owners.
Which workspaces see the offer#
Settings → Gateways shows Connect an account when the workspace manages its own gateways and at least one application is verified with its webhook value. See Connecting your provider account.
Revenue share and payouts#
A connected account receives the whole payment. Workspaces that share revenue with payees pay them from their own Stripe or PayPal account (their own-keys credential set as funding account), never through the platform's application: the money does not pass through the platform. See Payouts and Paying payees with Stripe.
Stripe Connect platform
With Stripe Connect a workspace gets (or links) its own Stripe account through hosted Stripe pages. Charges are direct charges: made on the workspace's account with the platform's key and the header Stripe-Account. The workspace is the merchant of record and pays Stripe's fees; the platform adds none.
Decide: Standard or Express#
The application asks for an account type and has no default, because the choice moves risk:
| Standard | Express | |
|---|---|---|
| Dashboard for the workspace | The full Stripe Dashboard | The lighter Express Dashboard |
| Onboarding | Hosted by Stripe | Hosted by Stripe |
| Negative balances (refunds or disputes larger than the balance) | Stripe's risk | The platform's risk |
| Disputes and refunds outside this system | The workspace can handle them in its Dashboard | Only through this system |
The type applies to accounts created from then on; existing accounts keep theirs.
Enable Connect#
- Sign in to the Stripe account that will be the platform (a separate account from any workspace's is cleanest).
- Settings → Connect → get started. Complete the platform profile; Stripe may ask what the platform does and who its users are.
- Under Connect → Settings → Branding, set the name and icon workspaces see during onboarding.
- Do this in test mode first. Live mode needs the platform profile approved by Stripe.
Add the application#
Super → Platform apps → Stripe:
- Platform publishable key and secret key — Developers → API keys of the platform account (
pk_test_…/sk_test_…for Test). - Connected account type — see above.
Save, then Verify: one call reads the platform account and one lists connected accounts, which Stripe refuses unless Connect is enabled.
Register the Connect webhook#
Developers → Webhooks → Add endpoint:
- Endpoint URL — the Platform webhook endpoint shown on the application's page.
- Choose Listen to events on Connected accounts. (An endpoint for "your account" receives nothing from workspaces.)
- Select the events listed under Events to send on the application's page:
account.updated,account.application.deauthorizedand the payment events. - Copy the endpoint's signing secret (
whsec_…) into Connect webhook signing secret.
Workspaces are offered Connect Stripe from this moment.
What a workspace does#
Settings → Gateways → Connect Stripe. The system creates the account at Stripe, then sends the owner to Stripe's onboarding pages. When Stripe has what it needs it sends the owner back; the set is Enabled as soon as Stripe accepts charges, which can be minutes or — when documents are reviewed — days. Meanwhile the set shows what Stripe still asks for, and Continue at Stripe opens a fresh link (Stripe's links expire after a few minutes and work once).
Bank payments (ACH): offered through a connected set only when the account's us_bank_account_ach_payments capability is active. Until then products show cards only for that set.
Ending a connection#
Disconnect on the set ends it here: the set is Revoked and no call is made for the account again. The Stripe account is the workspace's and is left as it is. If a workspace disconnects the platform inside Stripe instead, Stripe reports account.application.deauthorized and the set is revoked the same way.
Go live#
- [ ] Platform profile approved by Stripe for live mode.
- [ ] A Live application with
pk_live_…/sk_live_…and the account type. - [ ] A live Connect webhook endpoint with the live application's URL and its own signing secret.
- [ ] One workspace connected, one small real payment and refund.
Common errors#
"Only Stripe Connect platforms can work with other accounts" on Verify — Connect is not enabled on that Stripe account, or the key belongs to another account.
The set stays Restricted — the set's page lists what Stripe still needs (currently_due). The owner supplies it through Continue at Stripe.
Payments are made but stay Pending here — the Connect endpoint is missing, listens to "your account" instead of connected accounts, or its signing secret was not saved. The application's page shows the latest deliveries.
PayPal partner application
With PayPal Multiparty a workspace's PayPal Business account ("the seller") gives the platform's REST app permission to create orders, capture, refund and read disputes for it. Each call carries the platform's BN code and names the seller; the payment's payee is the seller. No platform fee is set.
What PayPal must approve first#
Seller onboarding uses the Partner Referrals API, which PayPal opens to approved partners only. Until then every connection attempt is refused by PayPal.
- Create a PayPal Business account for the platform, if there is none.
- At developer.paypal.com, apply to become a partner (PayPal Complete Payments / Multiparty). PayPal asks about the business model; say that sellers are paid directly and the platform takes no fee.
- PayPal enables the Partner Referrals API on your sandbox app first and issues a BN code (partner attribution ID). Production access follows its review.
Add the application#
Super → Platform apps → PayPal:
- Partner app Client ID and Secret — Apps & Credentials → the approved REST app (Sandbox for Test).
- Partner merchant ID — the merchant (payer) ID of the platform's own business account: PayPal → Account settings → Business information.
- BN code — as issued by PayPal.
Save, then Verify. The check obtains a token with the app's keys. PayPal has no call that shows whether the app may use the Partner Referrals API: that is proven when the first workspace connects.
Register the partner webhook#
In the same REST app → Add Webhook:
- Webhook URL — the Platform webhook endpoint shown on the application's page.
- Select the events listed under Events to send:
MERCHANT.ONBOARDING.COMPLETED,MERCHANT.PARTNER-CONSENT.REVOKEDand the payment events. - Copy the Webhook ID into the application.
Events of every seller who granted permission arrive at this one endpoint.
What a workspace does#
Settings → Gateways → Connect PayPal. The owner is sent to PayPal to sign in (or create a Business account) and grant the permissions: payments, refunds, reading disputes and the account's state. Back here, the system asks PayPal which seller completed the sign-up for that set, and for the seller's state:
- Enabled — the seller can receive payments, its e-mail address is confirmed and the permissions are granted.
- Restricted — the seller must confirm the e-mail address of the PayPal account, or PayPal has limited the account.
- Onboarding — the sign-up was not completed.
Ending a connection#
PayPal has no call with which a platform ends a seller's consent. Disconnect ends the connection here; the seller removes the permission in PayPal under Account settings → Website payments → API access. When a seller removes it there first, PayPal reports MERCHANT.PARTNER-CONSENT.REVOKED and the set is revoked.
Go live#
- [ ] PayPal's production approval for the partner app.
- [ ] A Live application with the live Client ID, Secret, merchant ID and BN code.
- [ ] The live webhook with the live application's URL and its Webhook ID.
- [ ] One seller connected, one small real payment and refund.
Common errors#
"PayPal could not start the connection" — the app is not approved for the Partner Referrals API in that environment, or the BN code belongs to another app. The set's page shows PayPal's own message.
The set stays in Onboarding after the owner returned — the owner left PayPal before granting the permissions. Continue at PayPal starts again.
PERMISSION_DENIED on a payment — the seller removed the permission. Press Check status now; the set becomes Revoked.
Square OAuth application
With Square OAuth the owner of a workspace signs in to Square and authorizes the platform's application. Square returns an access token for that seller, which this system stores encrypted, renews weekly and uses for the seller's payment links, subscriptions, refunds and disputes.
Create the application#
- Sign in at developer.squareup.com with the platform's Square account and create an application.
- Open OAuth. For Sandbox, then for Production:
- copy the Application ID and the Application secret;
- set the Redirect URL to the address shown as OAuth redirect URL on the application's page here.
Add the application#
Super → Platform apps → Square: Application ID and Application secret. Save, then Verify.
Square has no call that checks an application secret on its own. Verify checks the form of the values for the environment; the secret is proven the first time a workspace connects.
Register the webhook subscription#
Application → Webhooks → Subscriptions → Add subscription:
- Notification URL — the Platform webhook endpoint shown on the application's page, exactly as shown: Square signs the URL together with the body.
- Select the events listed under Events to send:
oauth.authorization.revokedand the payment events. - Open the subscription and copy its Signature key into the application.
What a workspace does#
Settings → Gateways → Connect Square. Square shows the permissions the application asks for:
MERCHANT_PROFILE_READ, PAYMENTS_READ, PAYMENTS_WRITE, ORDERS_READ, ORDERS_WRITE, ITEMS_READ, ITEMS_WRITE, CUSTOMERS_READ, CUSTOMERS_WRITE, SUBSCRIPTIONS_READ, SUBSCRIPTIONS_WRITE, INVOICES_READ, DISPUTES_READ.
After Allow, the set is Enabled when the account has an active US-dollar location with card processing. The first such location is chosen; an account with several can pick another on the set's page. Without one the set is Restricted.
In the sandbox, Square only authorizes while the sandbox test account's Seller Dashboard is open in the same browser (Developer Console → Sandbox test accounts → Open).
Tokens#
- The access token lives 30 days. The hourly job
connect.syncrenews every token older than 7 days, as Square recommends. - If renewal keeps failing and the token runs out, the set leaves service and the owners are e-mailed; connecting again repairs it.
- Disconnect revokes the application's access at Square and erases the tokens here. A seller who removes the application in Square causes
oauth.authorization.revoked, with the same result.
Go live#
- [ ] Production Application ID and secret in a Live application; the production Redirect URL registered.
- [ ] A production webhook subscription with the live application's URL and its signature key.
- [ ] One seller connected, one small real payment and refund.
Common errors#
"This connection link is not valid any more" — the authorization came back after 30 minutes, was opened twice, or by another member than the one who started it. Start again.
"Square did not complete the authorization" — usually the Redirect URL registered at Square differs from the one shown here, or the secret is from the other environment. The set's page shows Square's own message.
Restricted: no active US-dollar location — the Square account needs a location in USD with card processing enabled.
Authorize.net referral and Solution ID
Authorize.net has no connected accounts for a platform like this one. A workspace always uses its own API Login ID, Transaction Key and Signature Key. What the platform can add is:
- a referral link — workspaces open their Authorize.net account through it, so the account is credited to the platform's reseller or affiliate ID;
- a Solution ID — sent with every hosted payment request, so Authorize.net can tell that the payment came through this software.
Either can be used without the other.
Get the values#
- Referral link. Authorize.net's reseller and affiliate programs give a sign-up address that carries your ID, of the form
https://account.authorize.net/signUpNow?resellerID=…. Ask Authorize.net which program is open to you: availability for software platforms changes, and some programs require processing volume. - Solution ID. Issued to registered solution providers: Partner Interface → Account → Partner Account → Integrations. Sandbox and production IDs differ; Authorize.net publishes test IDs for the sandbox.
Add the application#
Super → Platform apps → Authorize.net → enter the link, the Solution ID, or both, for the environment. Verify checks their form and shows the host workspaces will be sent to. Authorize.net has no call that checks either value.
What workspaces see#
Settings → Gateways shows Open an Authorize.net account. It leads to your link. When the account exists, the owner adds its keys with Add credential set, as described in the Authorize.net gateway guide.
The Solution ID needs nothing from the workspace: while the application is Verified, every hosted payment request of that environment carries it — for every workspace, including sets that existed before.
Removing them#
Disable or delete the application. The link disappears from Settings → Gateways and the Solution ID is no longer sent. Workspaces' own sets are not affected.
Sandbox checklist for connected accounts
Run this once per provider after its platform application is Verified in Test and its webhook value is saved. It needs a browser, the provider's sandbox, and a workspace that manages its own gateways.
Stripe#
- As workspace owner: Settings → Gateways → Connect Stripe (Test). Stripe's onboarding opens.
- Complete it with Stripe's test data (test phone
000 000 0000, SMS code000-000, test bank account from Stripe's testing page). Use Continue at Stripe if a link expires. - Back on the set: connection Enabled, status Test, an account id
acct_…. - Choose the set for Stripe on a product, open the pay page, pay with card
4242 4242 4242 4242. - Check: the payment is Paid with a confirmation code; in the platform's Stripe Dashboard → Connect → the account, the payment is on the connected account and the platform's own balance is unchanged.
- Refund it from Transactions; check the refund on the connected account.
- Super → Platform apps → the application: the deliveries show
checkout.session.completedrouted to the set.
PayPal#
- Create a sandbox Business account for the seller at developer.paypal.com → Testing Tools → Sandbox accounts.
- As workspace owner: Connect PayPal (Test); sign in with the sandbox seller; grant the permissions.
- Back on the set: Enabled, with the seller's merchant id.
- Pay on a product's pay page with a sandbox Personal account.
- Check: Paid with a confirmation code; the money is in the sandbox seller's account, not the platform's.
- Refund it from Transactions.
- Start one subscription through the connected set and check that it activates.
Square#
- Developer Console → Sandbox test accounts → Open the seller's Dashboard and keep that tab open.
- As workspace owner: Connect Square (Test) → Allow.
- Back on the set: Enabled, with a location.
- Pay on a product's pay page with card
4111 1111 1111 1111, CVV111. - Check: Paid with a confirmation code; the payment is in the sandbox seller's Dashboard.
- Refund it from Transactions.
- In the seller's Dashboard remove the application (Apps → My applications); the set becomes Revoked within a minute.
Authorize.net#
- With a sandbox Solution ID saved and the application Verified, pay through any Authorize.net Test set.
- In the sandbox Merchant Interface open the transaction: the solution is shown in the transaction detail.
- As workspace owner: Open an Authorize.net account leads to your referral link.
If a step fails#
The set's page shows the provider's own last message. Super → Platform apps → the application shows the latest deliveries to the platform endpoint; Super → Self-check has an item for platform applications.