Upcoming changes and enhancements to the ConnectPay BaaS APIs. Please review these updates carefully, as they include both soft changes and breaking changes.
1. Soft Change: Expansion of the idvDeclineReason Enum
Target environment dates:
- Stage: September 16, 2026
- Production: September 22, 2026
To provide you and your customer support teams with more precise reasons for Identity Verification (IDV) declines, we are significantly expanding the idvDeclineReason enum list returned in the GET IDV Status API.
In addition to this enum expansion, we are introducing two new parameters to the API response to make it even easier for your support teams to troubleshoot and guide end users without needing manual lookups:
| Parameter | Type | Description |
|---|---|---|
idvDeclineDescription | string | A human-readable description of the specific idvDeclineReason returned. |
isRetryable | boolean | Indicates whether the verification issue is rectifiable. Tells customer support whether a retry should be recommended (true) or a deeper manual investigation is required (false). |
Previously, this field only supported three values: NotDetailed, Missing citizenshipCountryCode value for driver license, and OldTypeDocument. Going forward, the field will return detailed ConnectPay value mappings, including:
- Barcode issues: BarcodeNotFound
- Document data & readability: DataNotMatch, DocDateOfIssueError, DocDobError, DocExpiryError, DocNameError, DocNationalityError, DocNumberError, DocPersonalCodeInvalid, DocPersonalNumberError, DocGenderError, DocSurnameError, DocWithNonLatinCharacters, MrzInvalid, MrzNotFound, MrzReadingError
- Document quality & visibility: LightIssues, DocDamaged, DocNotVisible, DocNotFound, DocNotFullyVisible, DocTooBlurry
- Document validity & acceptance: CountryMismatch, CountryNotSupported, DocExpired, DocNotAllowed, DocSideMismatch, DocTypeMismatch
- Fraud & manipulation: Blacklisted, DocFake, DocPhoto (document from screen), DocPrinted, DocManipulation, DuplicatedInfo, FaceSuspected, FakeFace, PossibleFraudAttempt
- Face matching & selfies: DocFaceNotFound, FaceError, FaceNotClear, FaceMismatch, MissingFacePhoto, MoreThanOneFace, UnrelatedPhotoSubmit
- Other: Error (unclassified error)
Any unmapped or unrecognized vendor rejection reasons will default to NotDetailed.
The full list of IDV decline reasons, their descriptions, and the corresponding retry settings is available here: Identity verification with ConnectPay provider.
2. Breaking Change: Stricter Regex Validation on API Fields
Target environment dates:
- Stage: September 16, 2026
- Production: February 2, 2027
To ensure higher data quality and security, we are introducing a stricter regex pattern across several API fields:
^(?=[\p{L}\d])[\p{L}\d .,/\-:;'"()]*$This validation ensures that text inputs begin with a letter or digit, do not contain emojis or surrogate characters, and use a more limited set of special characters.
The following APIs and fields will be affected by this change:
Personal Onboarding API & Personal ODD API
person.address.addressLine1person.address.addressLine2person.address.cityaccount.purposesOfAccountOtheraccount.sourceOfIncomeOtheraccount.occupationAdditionalDetails.companyaccount.occupationAdditionalDetails.positionaccount.occupationAdditionalDetails.other
Business Onboarding API
company.businessActivityDescriptioncompany.registeredOfficeAddress.addressLine1company.registeredOfficeAddress.addressLine2company.registeredOfficeAddress.citycompany.headquartersOfficeAddress.addressLine1company.companyTypeOtheraccount.purposesOfAccountOtheraccount.sourceOfIncomeOtherpersons.address.addressLine1persons.address.addressLine2persons.address.citypersons.ownership.typeOtherpersons.ownership.hasVotingControlAdditionalInformationpersons.uboSourceOfWealthOther
Please ensure your front-end validations and back-end payloads are updated to comply with this regex pattern before February 2, 2027, to prevent payload rejections.
If you have any questions about these changes, please contact our technical support team at [email protected].