Error codes

In the unlikely event of timeout between Cardtokens.io and the schemes Cardtokens.io will return with an empty response and status code 0.

In the case Cardtokens.io declines the request by invalid data received, Cardtokens.io will be rejected by status code 500 followed by a payload of the rejection reason.

In the case of declines from the schemes Cardtokens.io will provide the full scheme decline message and pass that in a JSON response field named "err". Cardtokens.io returns the HTTP status code from the issuer directly. The content of "err" is JSON data, which is escaped.

Example for a Mastercard decline

{
  "err": "{\"errorCode\":\"PAN_INELIGIBLE\",\"errorDescription\":\"PAN Ineligible\",\"responseId\":\"91cfaa20-428d-4d28-8217-4314075da00e\",\"errors\":[{\"source\":\"INPUT\",\"description\":\"PAN Ineligible\",\"reasonCode\":\"PAN_INELIGIBLE\"}]}"
}

For Mastercard the format of the decline is:

• errorCode – a technical identification of the error
• errorDescription – a textual description of the error
• responseID – Unique identifier of the response.

The list of all Mastercard errorCode's / Reason code's is defined here.

The list of the Mastercard response codes is defined here.

Example for a Visa decline

{
  "err": "{\"errorResponse\":{\"status\":403,\"message\":\"Further operations are no longer allowed. Please contact your bank to resolve the issue.\",\"reason\":\"cardNotEligible\"}}"
}

For Visa the format of the decline is:

• errorResponse
  • Status
  • Message
  • Reason

Here is a list of the reason codes for Visa VTS:

Error Code	Reason Code	Description
400	invalidParameter	The value provided for one or more request parameters is considered invalid. Examples: - Missing required field. - The value exceeds the length specified for this field. - Field formatting does not match the expected format. - The details.location field of the error response may provide a list of fields which failed data validation constraints.
400	invalidRequest	The API server could not understand the request. This sometimes occurs when a data field is not in the appropriate/particular format. Examples: - Base64URL decoding failed. - The field is not in a particular format. - The message field may provide additional clarification of what part/field of the request is considered incorrect. - Refer to the API specification for the structure, format and constraints of the API request.
400	incompleteRequest	Missing required field. Refer to the details.location field to determine which fields failed data validation.
400	trConfigIssue	Token Requestor Configuration error. There is a problem with the Token Requestor’s configuration. Please verify your configuration at Visa.
401	authError	API Credentials and the encryption keys used do not match, or the API Key was invalid or does not exist.
401	inputValidationError	Authentication error. The API assertion/token is either not provided or invalid. Refer to API specification how to obtain valid credentials and format security assertion for authentication.
403	cardVerificationFailed	Invalid field. Invalid payment instrument or data associated with the payment instrument. The "location" field may point to the field failing the validation. Ask users to check that all information was entered correctly.
403	tokenUsageViolation	The purpose of the token does not match the intended usage of the token. Please, refer to the API specification about the expected usage of the token.
403	cardNotEligible	This card cannot be used for tokenization at this moment. Please try again later or choose another Visa card.
500	serviceError	An error happened on the server. Either show a generic message, or retry the same request again. The number of retries should be limited. Consider implementing Exponential Backoff. In this algorithm the delay before you retry is defined as: retryDelay = (2 ^ N) \* 1000 + randomDelayMs. retryDelay is the retry delay in milliseconds, N is your retry count (0, 1, 2, 3, …), and randomDelayMs is the random delay in milliseconds (0 .. 1000).
503	notReady	The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. If known, the length of the delay MAY be indicated in a Retry-After header.