Skip to main content

Troubleshoot user binding errors

This guide helps partner support teams identify, resolve, and prevent user binding errors.

For technical reference and API integration guides, see Fix a user binding error and Update a membership on docs.swan.io.

Key takeaways
  • A binding error occurs when the details you provided for an invited account member don't match their sign-up details.
  • You can spot binding errors from your Dashboard. To fix them, correct the membership details from your partner interface. If your integration doesn't support that, direct an account member who has the canManageAccountMembership permission, usually the legal representative, to resolve the error in Web Banking.
  • Users can often fix three error types themselves: emailVerifiedMatchError, idVerifiedMatchError, and phoneNumberMatchError. If the identification link has expired, share a new one. If the email doesn't match, raise a Swan Support request.
  • The most important prevention tip: check spelling against the user's identity document, not their preferred name.
  • The most important prevention tip: check spelling against the user's identity document, not their preferred name.

Understand binding errors​

A binding error occurs when the information you provided when inviting an account member doesn't match the information they provided during sign-up. Until the error is resolved, the member can't perform sensitive operations. What the member can see depends on your integration. They may still be able to view account or card information, or they may not be able to access anything.

Binding errors only occur during initial binding. Updating personal details on an Enabled membership doesn't cause a binding error.

ScenarioError codeExampleResolved by
Name spelling mismatchfirstNameMatchError, lastNameMatchErrorYou entered "Dupond" but the ID says "Dupont"Legal representative
Married vs. birth namelastNameMatchErrorYou used the married name but the ID shows birth nameLegal representative
Phone number typophoneNumberMatchErrorA digit was wrong when membership was createdLegal representative
Date format swapbirthDateMatchErrorDay and month swapped (03/06 vs. 06/03)Legal representative
Different emailemailVerifiedMatchErrorInvited with work email; user signed up with personal emailSwan Support
Email not verifiedemailVerifiedMatchErrorEmail matches but user hasn't clicked the verification linkUser, see how users fix it
Identification not completedidVerifiedMatchErrorUser hasn't completed the required identificationUser, see how users fix it

Spot a binding error​

  1. Go to Dashboard > Data > Account memberships.
  2. Filter for membership status BindingUserError.
  3. Select the affected user.

Your Dashboard shows all mismatched information. The Dashboard doesn't let you correct membership data directly. Your user may be able to correct the mismatch themselves, depending on your integration. Check the integration setup before moving on.

No BindingUserError status?

If you don't see a BindingUserError status, the user may not have accepted the invitation and completed the sign-up process yet. Check the InvitationSent status. If it shows that the invitation was sent, ask the user to accept it. If they haven't received it, the person who sent the invitation can resend the link.


Fix a binding error through your partner interface​

Use your partner interface to correct the mismatched membership information. If your interface doesn't expose membership management, ask your development team to add this capability using the Account Membership API.

If your integration doesn't provide a correction flow, direct an account member with the canManageAccountMembership permission, typically the legal representative, to resolve the error in Web Banking. Share the Resolve a user binding error article on support.swan.io with them for step-by-step instructions.

Resolving through Web Banking

This is the recommended fix path for partners not using the Swan API. It remains an option for partners with API integrations where membership management isn't exposed to users.


Help users fix their own binding errors​

Three types of binding errors can be resolved by the user without your intervention. For all other error types, see Understand binding errors.

Email not verified (emailVerifiedMatchError)​

Tell your user to:

  • Check their inbox for a verification email from Swan.
  • Select the link to verify their email address.
  • Check their spam folder if they can't find the email.

Make sure they're using the same email they originally signed up with.

Wrong email address verified

If the user verifies a different email address than the one shown on their membership, raise a support request in your Dashboard. Include the correct email address and phone number.

Identification not completed (idVerifiedMatchError)​

Tell your user that they need to complete their identity verification. Ask them to open the link they received by email or SMS to start.

If the user's identification link has expired or is no longer accessible, send them a new one through the Dashboard.

Phone number mismatch (phoneNumberMatchError)​

This error occurs when the phone number the user signed up with doesn't match the number entered when their membership was created. This might be caused by a typo or by the user signing up with a completely different number.

First, confirm which phone number the user should use:

  • If the phone number on the membership is correct and both numbers belong to the same person, ask the user to update their sign-in number using Swan's phone number update flow. They must open the link on a mobile phone and complete the entire process. The binding error clears automatically after the number is updated.
  • If the number the user signed up with is correct, an account member with permission to manage memberships must update the phone number on the membership.
  • If either number belongs to someone else, don't ask the user to update their number. Raise a Swan Support request.

Prevent binding errors​

  1. Check spelling against the identity document. Use the exact name on the ID, not their preferred name.
  2. Use the user's birth name, not their married name.
  3. Confirm the phone number format. Include the country code (for example, +33 for France or +49 for Germany).
  4. Verify the email address. Confirm which email the user will sign up with.
  5. Don't swap day and month in birth dates.

Contact Swan Support​

Raise a Swan Support request if:

  • The error persists after the legal representative corrected the mismatched information and gave consent.
  • The membership is stuck in BindingUserError after the user has completed identification and email verification.
  • You need to resolve a binding error for the legal representative's membership.

Include in your request:

  • Account ID and account membership ID
  • The specific error types
  • Resolution steps already taken

Share these articles with your users​

Help center content

You can also use these articles as a starting point to create your own FAQ or help center content, tailored to your product's terminology and your users' specific context.