Configuration Errors

Configuration errors are detected by the SDK and thrown to the console due to misconfigurations in the object passed to the openForm function.

Error Message	Description	How to solve
[Card Enrollment SDK]: Error parsing config field: "getAccessToken" message: "Is required"	`getAccessToken` is missing from the configurations	Please provide a `getAccessToken` function.
[Card Enrollment SDK]: Error parsing config field: "getAccessToken" message: "Must be a function"	`getAccessToken` is not a function	Please provide a `getAccessToken` function.
[Card Enrollment SDK]: Error parsing config field: "subaccountId" message: "Is required"	`subaccountId` is missing from the configurations	Please provide a valid UUID v4 `subaccountId`.
[Card Enrollment SDK]: Error parsing config field: "subaccountId" message: "Must be a valid UUID v4"	`subaccountId` is not in valid UUID v4 format	Please provide a valid UUID v4 `subaccountId`.
[Card Enrollment SDK]: Error parsing config field: "companyName" message: "Is required"	`companyName` is missing from the configurations	Please provide a string value for `companyName`.
[Card Enrollment SDK]: Error parsing config field: "companyName" message: "Must be a string"	`companyName` is not of string type	Please provide a string value for `companyName`.
[Card Enrollment SDK]: Error parsing config path: "terms" message: "Unrecognized key(s) in object: 'terms'"	Unrecognized key in the config object	Please review the config keys provided.
[Card Enrollment SDK]: Error parsing config path: "terms.text" message: "Expected string, received number"	`terms.text` is not of string type	Please provide a string value for `terms.text`.
[Card Enrollment SDK]: Error parsing config path: "terms.termsUrl" message: "Invalid url"	`terms.termsUrl` is not a valid URL	Please provide a valid URL for `terms.termsUrl`.
[Card Enrollment SDK]: Error parsing config path: "terms.termsUrl" message: "Expected string, received number"	`terms.termsUrl` is not a valid URL	Please provide a valid URL for `terms.termsUrl`.
[Card Enrollment SDK]: Error parsing config path: "terms.privacyUrl" message: "Invalid url"	`terms.privacyUrl` is not a valid URL	Please provide a valid URL for `terms.privacyUrl`.
[Card Enrollment SDK]: Error parsing config path: "terms.privacyUrl" message: "Expected string, received number"	`terms.privacyUrl` is not a valid URL	Please provide a valid URL for `terms.privacyUrl`.
[Card Enrollment SDK]: Error parsing config path: "container" message: "Input not instance of HTMLElement"	`container` is not a valid HTMLElement	Please provide a valid HTMLElement for `cointaner`.

Enrollment Errors

These errors are sent to the onError callback if it is defined by the customer. Errors can be of Client or Server type and will have the following error format:

Example Payload (Server Error):

{
  "type": "server",
  "error": {
    "detail": "Card verification step with id=d397da41-95ac-4bb0-82da-cd78d10d06ff for card verification with id=ed146b4a-8e48-4c7f-b284-62eb64dca7bb can not be completed at this state",
    "title": "Bad Request"
  }
}

Example Payload (Client Error):

{
  "type": "client",
  "error": {
    "detail": "The provided token is not a valid JWT token."
  }
}

Server Errors

Error Type	Error Title	Error Detail	Description	How to solve
Server	Unauthorized	Authentication credentials were either missing or incorrect.	The credentials used are either invalid or not present.	Please check the `getAccessToken` function specified in the configuration. If it is correctly configured, please contact support.
Server	Forbidden	You do not have the necessary permission to access the requested resource.	The credentials used are valid but do not have sufficient permission to access the resource.	Please check the `getAccessToken` function specified in the configuration. If it is correctly configured, please contact support.
Server	Not Found	Subaccount with the given ID was not found.	The specified subaccount was not found.	Please check the subaccount specified in the SDK configuration.
Server	Internal Server Error	Unknown error occurred.	The account service is unable to process the request.	Please wait a few moments and retry. if the problem persists, please contact support.
Server	Bad Request	Request object failed validation	The card details entered did not pass the validation.	Check the card details and try again.
Server	Forbidden	Subaccount has insufficient configurations to allow this action	The enrolled card was issued in a country not supported by the subaccount.	You can either revisit the subaccount configuration or change the subaccount.
Server	Forbidden	Missing scope 'card-subscriptions:write'	The credentials used does not have the required 'card-subscriptions:write' scope.	Please use an access token with the required scopes.
Server	Forbidden	Missing scope 'card-subscriptions:read'	The credentials used does not have the required 'card-subscriptions:read' scope.	Please use an access token with the required scopes.
Server	Internal Server Error	An unexpected error happened while creating a card subscription	The card subscription service is unable to process the request.	Please wait a few moments and retry. if the problem persists, please contact support.
Server	Bad Request	Unsupported card network provider {network}	The enrolled card network is not supported. Only Visa and MasterCard networks are supported.	Please try to enroll a different card.
Server	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request	The card verification service is unable to process the request.	Please wait a few moments and retry. if the problem persists, please contact support.
Server	Forbidden	Credentials used do not have permission to perform the request	The credentials used does not have the required card-verifications scope.	Please use an access token with the required scopes.
Server	Not Found	Card verification step with id=fingerprint for card verification with id={verificationId} not found	The card verification fingerprint step was not found.	Please wait a few moments and retry. if the problem persists, please contact support.
Server	Not Found	Card verification step with id=challenge for card verification with id={verificationId} not found	The card verification challenge step was not found.	Please wait a few moments and retry. if the problem persists, please contact support.
Server	Not Found	Card verification with id={verificationId} not found	The card verification was not found.	Please wait a few moments and retry. if the problem persists, please contact support.
Server	Bad Request	Invalid card provided	The provided card does not have a subscription that requiries verification.	Please wait a few moments and retry. if the problem persists, please contact support.
Server	Bad Request	Invalid card details provided	The provided card is not eligible for verification.	Please try with a new card. if the problem persists, please contact support.
Server	Bad Request	Card verification step with id=fingerprint for card verification with id={verificationId} not in in-progress state anymore	The card verification fingerprint step is not in progress state.	Retry the enrollment process. If it continues failing, please wait for 1 hour for the current verification to expire, then retry the process again.
Server	Bad Request	Card verification step with id=challenge for card verification with id={verificationId} not in in-progress state anymore	The card verification challenge step is not in progress state.	Retry the enrollment process. If it continues failing, please wait for 1 hour for the current verification to expire, then retry the process again.
Server	Bad Request	Card verification step with id=challenge for card verification with id={verificationId} can not be completed at this state	Card network provider considered authentication as not completed.	Wait for 1 hour for the current verification to expire, then retry the process again.

Client Errors

Error Type	Error Title	Error Detail	Description	How to solve
Client	-	Invalid access token: Access token is malformed. Expected to be a Json Web Token.	`getAccessToken` function configured returns an invalid token.	Update the function method to return a valid JWT token.
Client	-	Invalid access token: The provided token is not a valid JWT token.	`getAccessToken` function configured returns an invalid token (not a JWT).	Update the function method to return a valid JWT token that follows the JWT standard.
Client	-	Timeout while waiting for token. Ensure that getAccessToken is returning a valid token within the allowed time window (5s).	`getAccessToken` function configured takes longer than 5 seconds to return a JWT.	Update the function method to return a JWT in a shorter time.
Client	-	Error getting a valid IP	May occur when obtaining the customer's IP address to perform fingerprinting.	Check if any browser extension or VPN is running.
Client	-	Verification state is 'failed'. Cannot proceed with 3DS verification.	3DS card verification failed.	Retry the enrollment process. If it continues failing, wait for 1 hour for the current verification to expire, then retry the process again.
Client	-	There is already an ongoing verification for this card, but it failed to return.	Failed to fetch current card verification.	Wait for 1 hour for the current verification to expire, then retry the process again.
Client	-	Verification type expected to be 3DS.		Retry the enrollment process. If it continues failing, wait for 1 hour for the current verification to expire, then retry the process again.
Client	-	An error occurred while verifying the card.	Some unexpected error occurred during the enrollment.	Wait for 1 hour for the current verification to expire, then retry the process again.
Client	-	Unexpected challenge state '{state}'.	Some unexpected error occurred during the challenge step.	Wait for 1 hour for the current verification to expire, then retry the process again.
Client	-	Unexpected fingerprint state 'state'. This state is expected to be 'completed', or the outcome to be 'requires-challenge'.	Some unexpected error occurred during the fingerprinting step.	Wait for 1 hour for the current verification to expire, then retry the process again.

Account Status Inquiry (ASI) Error:

If you receive the following error, this indicates that the card verification process has failed due to an Account Status Inquiry (ASI) check.

{
  "title": "Bad Request",  
  "detail": "The card provided did not pass the Issuer's Account Status Inquiry (ASI)"  
}

Understanding the ASI Error

The Account Status Inquiry (ASI) is a verification process used to check the status and validity of a card. When this check fails, it means the card issuer has declined to authorize the card based on the current status of the account.

Here are the potential reasons why a card verification can fail the Account Status Inquiry (ASI):

Card-related:

Card not activated: A new card that hasn't been activated by the cardholder.
Invalid PAN: The provided card number is incorrect or does not exist.
Incorrect CVV/CVC: The provided security code doesn't match the one on file.
Expired card: The card's expiration date is incorrect.
Restricted card: The card has usage restrictions that prevent the verification transaction.
International restrictions: The card may not be authorized for use in certain countries or regions, or process cross border transactions.
Online transaction restrictions: The card may not be authorized to process online transactions.
Lost or stolen card: The card has been flagged as lost or stolen.
Daily limit exceeded: The card has reached its daily transaction limit.

Account-related:

Closed account: The card account has been closed by the issuer or cardholder.
Insufficient funds: The account lacks the necessary funds for the verification transaction.
Frozen account: The account has been temporarily frozen due to suspicious activity or other reasons.
Fraud alerts: Active fraud alerts on the account may trigger a failure.
Incorrect Issuer country: A mismatch in the provided address information.

Issuer-related:

Technical issues: Problems with the issuer's or processor's systems can cause verification failures.
Issuer decline: The card issuer declines the verification for undisclosed reasons.