Connected accounts: how they work
Platform applications, connected credential sets, where the money goes, the four connection statuses, the platform webhook endpoints and what protects a connection.
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.