API guidelines

Development considerations

The following changes are considered backward compatible:

• Add a new API request.

• Add a new optional parameter to an existing API request or response.

  • Add it in the body, as a query parameter, or as an HTTP header.

• Add a new enum value.

• Make required parameters optional.

• Ignore unknown fields or values received in an API request or response.

Error management

Responses and error types

Responses are grouped into categories. Handle all responses in the same category the same way. The following table lists the categories and indicates:

• The error types in each category.

• How the issuer backend must handle these errors, including the retry policy.

CODE TYPE	CATEGORY	DESCRIPTION AND RETRY POLICY
K	OK, not an error	N/A
D	Data Error	The parameters sent by the function requester do not match with the rules checked by the function provider.
S	System Error	This is an unexpected error caused by a temporary failure in one or more parts of the system. The function requester can retry the request. Note: HTTP 5xx errors are considered system errors.
F	Functional Error	This is a definitive error. Abort processing. Do not retry. The token can no longer be used and must be deleted.

Errors

The table below lists the errors that can occur.

Depending on the flow, an error can be returned either synchronously in the response or asynchronously in a callback.

ERROR CODE	CODE TYPE	DESCRIPTION
111	D	Missing required parameter
112	D	Bad parameter format
113	D	Unknown issuer
114	D	Unknown end user
115	D	Unknown product
116	D	Unknown card
117	D	Unknown token storage
118	D	Unknown request
119	D	Unknown virtual card
158	D	Invalid parameters: card expired
159	D	Invalid parameters: card suspended
160	D	Invalid parameters: card revoked or deleted
161	D	Authentication value is incorrect. Incorrect card security code (CSC) Invalid cryptographic OTP
163	D	Product not supported for mobile payment
164	D	FPAN Provisioning Count Exceeded
166	D	Invalid card information (FPAN, expiry date) or card not eligible
167	D	Card already enrolled
168	D	No phone number associated with the end user
221	S	Device or wallet provider is not accessible after retries
222	S	Device or wallet provider is busy
231	F	Unexpected error from the device
232	F	Insufficient memory on the device to perform the operation
321	S	Operation on a token is already ongoing
322	S	Operation time-to-live expired
323	S	Operation partially completed (typically when an operation targets multiple virtual cards and one fails)
421	S	OTP or PIN locked (retry limit exceeded)
422	S	OTP expired
431	F	Invalid personalization data
432	F	Current token/card state does not allow this operation
501	D	ID&V method ID is invalid
502	D	Communication channel is not available to send OTP
503	D	ID&V method selected by the end user is no longer valid. This can happen if, during enrollment, the channel data (for example, a phone number) becomes invalid for the ID&V process.
510	F	Step-up cardholder verification declined (Visa CTF only)
520	F	Step-up cardholder verification failed (Visa CTF only)
521	S	Push server error
531	F	Push token no longer valid
911	F	Operation failed
920	F	OTP generation limit exceeded
921	S	Unexpected server error