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.
- 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
canManageAccountMembershippermission, usually the legal representative, to resolve the error in Web Banking. - Users can often fix three error types themselves:
emailVerifiedMatchError,idVerifiedMatchError, andphoneNumberMatchError. 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.
| Scenario | Error code | Example | Resolved by |
|---|---|---|---|
| Name spelling mismatch | firstNameMatchError, lastNameMatchError | You entered "Dupond" but the ID says "Dupont" | Legal representative |
| Married vs. birth name | lastNameMatchError | You used the married name but the ID shows birth name | Legal representative |
| Phone number typo | phoneNumberMatchError | A digit was wrong when membership was created | Legal representative |
| Date format swap | birthDateMatchError | Day and month swapped (03/06 vs. 06/03) | Legal representative |
| Different email | emailVerifiedMatchError | Invited with work email; user signed up with personal email | Swan Support |
| Email not verified | emailVerifiedMatchError | Email matches but user hasn't clicked the verification link | User, see how users fix it |
| Identification not completed | idVerifiedMatchError | User hasn't completed the required identification | User, see how users fix it |
Spot a binding error
- Go to Dashboard > Data > Account memberships.
- Filter for membership status
BindingUserError. - 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.
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.
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.
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
- Check spelling against the identity document. Use the exact name on the ID, not their preferred name.
- Use the user's birth name, not their married name.
- Confirm the phone number format. Include the country code (for example, +33 for France or +49 for Germany).
- Verify the email address. Confirm which email the user will sign up with.
- 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
BindingUserErrorafter 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
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.
- Resolve a user binding error: fixing the error in Web Banking, step by step.
- Add a member to your account: inviting a new member with correct details.
- Identification process overview: what to expect during identification.