Skip to main content
Connect lets an existing Ionic merchant grant your platform access to their account. Your server starts the request, the merchant approves it on Ionic, and your server exchanges the returned code for the merchant ID and granted permissions. This flow connects an existing account; it does not create one.

​
Before you begin

  • An active Platform Program with the permissions and mode your integration uses.
  • A platform secret key with platform:act. Keep it on your server.
  • An approved HTTPS redirect origin. The callback must be exactly that origin followed by /connect/callback, for example https://platform.example.com/connect/callback, with no query string or fragment.
Redirect origins are separate from payment domains. The requests on this page use your platform key without Ionic-Account.

​
1. Start the connection on your server

Create a random, single-use state and a PKCE verifier for this attempt. The verifier is a cryptographically random string of 43–128 characters. Derive code_challenge by SHA-256 hashing the verifier, then encoding the digest as base64url without padding. Use S256 as the challenge method. Store the state, verifier, exact callback URI, and test/live mode against the signed-in user starting the connection. Keep the verifier on your server. Call POST /v1/account_authorizations with those values and only the permissions your integration needs. This example requests payment access; substitute the state and challenge generated for the attempt:
Save the returned authorization id (aauth_…) with that attempt. Redirect the merchant’s browser to the returned authorization_url before expires_at. Reuse the same idempotency key and body when retrying this create request. For card saving, request setup_intents:read and setup_intents:write instead. Add customers:write if you create customer records, and customers:read if you read them. Requested permissions must be allowed by your Platform Program; they do not expand your API key’s permissions.

​
2. Handle the merchant’s decision

Ionic redirects to your callback with the original state and either a one-time code or an error. Verify that state matches the pending attempt for the signed-in user before accepting either result. Reject missing or mismatched state. If the merchant denies access, show that the connection was not completed; do not exchange a code. For an expired attempt, let the user start again. Keep callback codes and the PKCE verifier out of logs and analytics.

​
3. Exchange the code on your server

Use the saved authorization ID, the callback code, the original verifier, and the exact callback URI from step 1. Use the platform credential in the same mode. Replace the example body values with the values from that attempt:
A successful response has status: "approved", account (the merchant’s mer_… ID), permissions, and livemode. It returns the approved connection result, not a new API key. For a retry, preserve the exchange’s idempotency key and request body. A code is single-use. Store the returned merchant ID and mode against the authorized business in your application, together with the granted permissions. Mark the pending attempt complete so the callback cannot link the merchant again. Do not take the merchant ID from an unverified browser parameter.

​
4. Use the connected merchant

GET /v1/connected_accounts/{id} reads the current connection. Check its connection_status, account_status, payments_enabled, permissions, and livemode before offering payment features. Approval connects the merchant; it does not activate their payment capability. Access can change after approval. For merchant-owned resources, use your platform key and select that merchant with Ionic-Account, or the SDK’s account option. Use the same merchant ID in the browser client. Your key and the active connection must both allow the operation. See How Connect works. Continue with Accept payments or Save cards. See API Reference → Platform Connect for authorization and connected-account endpoints.