Core Resources
Payment Methods
Money Management
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Create an Account Link v2

Core Resources
Account Links
Create an Account Link

Creates an AccountLink object that includes a single-use Stripe URL that the merchant can redirect their user to in order to take them to a Stripe-hosted application such as Recipient Onboarding.

Learn more about calling API v2 endpoints.

Parameters

  • accountstringRequired

    The ID of the Account to create link for.

  • use_caseobjectRequired

    The use case of the AccountLink.

    • use_case.account_onboardingobject

      Indicates that the AccountLink provided should onboard an account.

      • use_case.account_onboarding.configurationsarray of enumsRequired

        Open Enum. A v2/account can be configured to enable certain functionality. The configuration param targets the v2/account_link to collect information for the specified v2/account configuration/s.

        Possible enum values
        recipient

        To onboard a new recipient.

      • use_case.account_onboarding.refresh_urlstringRequired

        The URL the user will be redirected to if the AccountLink is expired, has been used, or is otherwise invalid. The URL you specify should attempt to generate a new AccountLink with the same parameters used to create the original AccountLink, then redirect the user to the new AccountLink’s URL so they can continue the flow. If a new AccountLink cannot be generated or the redirect fails you should display a useful error to the user. Please make sure to implement authentication before redirecting the user in case this URL is leaked to a third party.

      • use_case.account_onboarding.return_urlstring

        The URL that the user will be redirected to upon completing the linked flow.

    • use_case.account_updateobject

      Indicates that the AccountLink provided should update a previously onboarded account.

      • use_case.account_update.configurationsarray of enumsRequired

        Open Enum. A v2/account can be configured to enable certain functionality. The configuration param targets the v2/account_link to collect information for the specified v2/account configuration/s.

        Possible enum values
        recipient

        To update a new recipient.

      • use_case.account_update.refresh_urlstringRequired

        The URL the user will be redirected to if the AccountLink is expired, has been used, or is otherwise invalid. The URL you specify should attempt to generate a new AccountLink with the same parameters used to create the original AccountLink, then redirect the user to the new AccountLink’s URL so they can continue the flow. If a new AccountLink cannot be generated or the redirect fails you should display a useful error to the user. Please make sure to implement authentication before redirecting the user in case this URL is leaked to a third party.

      • use_case.account_update.return_urlstring

        The URL that the user will be redirected to upon completing the linked flow.

    • use_case.typeenumRequired

      The type of AccountLink the user is requesting.

      Possible enum values
      account_onboarding

      A form to collect all required information to onboard a new account.

      account_update

      A form to collect all required information to update a previously onboarded account.

Returns

Response attributes

  • objectstring, value is "v2.core.account_link"

    String representing the object’s type. Objects of the same type share the same value of the object field.

  • accountstring

    The ID of the Account the link was created for.

  • createdtimestamp

    The timestamp at which this AccountLink was created.

  • expires_attimestamp

    The timestamp at which this AccountLink will expire.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • urlstring

    The URL for the AccountLink.

  • use_caseobject

    The use case of AccountLink the user is requesting.

    • use_case.account_onboardingnullable object

      Indicates that the AccountLink provided should onboard an account.

      • use_case.account_onboarding.configurationsarray of enums

        Open Enum. A v2/account can be configured to enable certain functionality. The configuration param targets the v2/account_link to collect information for the specified v2/account configuration/s.

        Possible enum values
        recipient

        To onboard a new recipient.

      • use_case.account_onboarding.refresh_urlstring

        The URL the user will be redirected to if the AccountLink is expired, has been used, or is otherwise invalid. The URL you specify should attempt to generate a new AccountLink with the same parameters used to create the original AccountLink, then redirect the user to the new AccountLink’s URL so they can continue the flow. If a new AccountLink cannot be generated or the redirect fails you should display a useful error to the user. Please make sure to implement authentication before redirecting the user in case this URL is leaked to a third party.

      • use_case.account_onboarding.return_urlnullable string

        The URL that the user will be redirected to upon completing the linked flow.

    • use_case.account_updatenullable object

      Indicates that the AccountLink provided should update a previously onboarded account.

      • use_case.account_update.configurationsarray of enums

        Open Enum. A v2/account can be configured to enable certain functionality. The configuration param targets the v2/account_link to collect information for the specified v2/account configuration/s.

        Possible enum values
        recipient

        To update a new recipient.

      • use_case.account_update.refresh_urlstring

        The URL the user will be redirected to if the AccountLink is expired, has been used, or is otherwise invalid. The URL you specify should attempt to generate a new AccountLink with the same parameters used to create the original AccountLink, then redirect the user to the new AccountLink’s URL so they can continue the flow. If a new AccountLink cannot be generated or the redirect fails you should display a useful error to the user. Please make sure to implement authentication before redirecting the user in case this URL is leaked to a third party.

      • use_case.account_update.return_urlnullable string

        The URL that the user will be redirected to upon completing the linked flow.

    • use_case.typeenum

      The type of AccountLink the user is requesting.

      Possible enum values
      account_onboarding

      A form to collect all required information to onboard a new account.

      account_update

      A form to collect all required information to update a previously onboarded account.

Error Codes
404not_found

The resource wasn’t found.

POST /v2/core/account_links
curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-04-30.preview" \
  --json '{
    "account": "acct_1Nv0FGQ9RKHgCVdK",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient"
            ],
            "return_url": "https://example.com/return",
            "refresh_url": "https://example.com/reauth"
        }
    }
  }'
Response
{
  "object": "v2.core.account_link",
  "account": "acct_1Nv0FGQ9RKHgCVdK",
  "created": "2025-03-27T17:15:18.000Z",
  "expires_at": "2025-03-27T17:25:18.000Z",
  "url": "https://accounts.stripe.com/r/acct_1Nv0FGQ9RKHgCVdK#alu_test_61SGhyomRuz7xsw5216SGhyj0ASQdCLwMKdRUF3mi3H6",
  "use_case": {
    "account_onboarding": {
      "configurations": [
        "recipient"
      ],
      "refresh_url": "https://example.com/reauth",
      "return_url": "https://example.com/return"
    },
    "type": "account_onboarding"
  }
}