Skip to main content
An Account Link (alink_…) is a single-use URL that takes one merchant through Ionic’s hosted signup, connection, and onboarding for one of your Connect configurations. Your server creates the link, saves its ID, and redirects the merchant’s browser to the returned url. When the merchant finishes or leaves, Ionic sends the browser to your return_url with account_link added to the query. Your server then reads the link to find the merchant’s ID. For the full flow, see Connect a new merchant. For a new-merchant configuration, Ionic creates the merchant’s account from prefill. Your platform can act for that account only after its owner verifies their email and agrees to connect, which creates the Connection. The merchant’s ID becomes the connected account you select with Ionic-Account. Both requests use your platform secret key, and the key’s mode decides whether the link is test or live.

​
Attributes

​
string
Account Link ID. Save it with your customer before redirecting; the return carries it back.
​
string
Single-use URL for the merchant’s browser. Redirect to it right away; don’t email or message it.
​
string
When url stops working, 30 minutes after creation.
​
string
How the merchant’s visit went. It describes the visit, not payment readiness. - in_progress: the merchant hasn’t finished or left yet. - merchant_actions_completed: the merchant did everything this visit needed: connected, and signed the application if the configuration includes one. Payments may still be under review. - cancelled: the merchant left before connecting. - incomplete: the merchant connected, then left before finishing. - expired: the link or visit expired first. - blocked: the Account or Connection can no longer be used, or the application was closed.
​
string
The merchant’s Account ID. Send it as the Ionic-Account header on requests you make for the merchant. For a new-merchant configuration it’s present from creation, before consent, and doesn’t by itself let you act for the merchant; wait for connection_id.
​
string
Where the merchant is in onboarding. For connect-only configurations it is absent once the owner consents. Read the current value rather than inferring it from the return. - awaiting_consent: Ionic created the Account; the owner hasn’t clicked Connect yet. - collecting: the merchant is filling in the application. - awaiting_signature: submitted, waiting for the merchant to sign. - under_review: signed; Ionic is reviewing it. - approved: the Account can take live payments, including a merchant who already could. - closed: the application was closed and can’t continue.
​
boolean
Whether the Account can take payments in this link’s mode right now.
​
string
Current status of connection_id: active, suspended, or disconnected. Present after consent.
See every field in the response of Retrieve hosted onboarding progress.

​
Endpoints

​
Statuses

A link result reports three separate things. Check each one. outcome describes how the merchant’s visit went. It does not describe payment readiness. onboarding_status reports where the merchant is in onboarding. For connect-only configurations it is absent once the owner consents. Read the current value rather than inferring it from the return. payments_enabled is true when the account can take payments in the link’s mode right now. connection_status is active, suspended, or disconnected, and is present after consent.

​
Rules

  • The url works once and expires 30 minutes after creation. Redirect to it right away. Do not email or message it, because link previews can open it first.
  • Send an Idempotency-Key on create. Retrying with the same key and body returns the same link. The same key with a different body returns 409. See Idempotency.
  • The return tells you which link to look at, not what happened. Look up the account_link value in your own records, then save connected_account_id and connection_id from the API response, never from the browser.
  • To continue an expired or abandoned visit, create a new link with resume_from set to the earlier link ID.
  • Subscribe to account.updated for later changes to payments_enabled. See Webhooks for platforms.