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, direct an account member who has the
canManageAccountMembershippermission, usually the legal representative, to resolve the error in Web Banking. - Users can often fix two error types (
emailVerifiedMatchErrorandidVerifiedMatchError) themselves. If the email doesn't match or the identification link has expired, raise a support request in your Dashboard. - 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 they can see depends on your integration: some members may still view account and card information; others may see nothing at all.
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.
If you don't find a BindingUserError status, the user may not have accepted the invitation and completed sign-up yet. This isn't a binding error. Raise a support request in your Dashboard for guidance.
Fix a binding error from Web Banking
If the affected account has a member with the canManageAccountMembership permission (typically the account's legal representative), they can resolve binding errors directly 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
Two 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, raise a support request in your Dashboard to issue a new one. Include the account membership ID in your 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
Share these Support Center articles with users who have questions about account membership:
- 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.
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.