eCOM Tokenizer Developer Portal

API Philosophy

The eCOM Tokenizer API is split into 2 parts: the tokenizer API and a static resource download API.

The tokenizer API is an RPC-style HTTP API.

• It uses the HTTP protocol as a transport medium, and restricts only to the HTTP POST method.
• These services can be considered as remote procedure calls that expect a JSON message in the request and deliver a JSON message in the response.
• All the use cases are implemented by this tokenizer API, except the static resource download functionality.
• Every API call has to contain a gd-request-id HTTP header (see details below and within the OpenApi spec).

The gd-request-id

• is part of each API call.
• It shall be a customer defined unique request identifier.
• This identifier is used to trace customer requests through the G+D system.
• It shall be provided to G+D support calls along with dedicated use case/failure/input information.
• It is a mandatory HTTP header parameter and shall consist of a combination of alphanumeric characters and the - sign with a maximum of 64 characters.
• For automatic integration e.g. a combination of a custom defined prefix and UUIDs maybe used, e.g. CUST-XYZ-64893814-4259-455e-9b17-20300e209e11.

The static resource API

• Can be used to download static token metadata and other static resources.
• It can be called with standard HTTP GET request
• It delivers the requested JSON formatted resource.

Backward compatibility

• API changes are made in an attempt to keep backwards compatibility whenever possible.
• However, new data might be added frequently with newer versions.
• This new data is NOT considered as backward incompatibility.
• Please make sure that NEW data fields, which are not part of the current local API version do NOT break your services during the validation of API responses.

API Versioning

Environment specific default version

• Each environment is defining a default version.
• Current default is 2.1 for SANDBOX and PRODUCTION.

Request specific version

• Starting with API 2.1 and API 3.0, version specific endpoints are exposed for each API version.
• Customers have to decide which version to use. The current default version is 2.1.
• For details see version specific release dates in API References.
• Note: For notifications the Customer specific or environment default version is used.

Customer specific version for notification handling

• Customers may request to use a different version per environment.
• Customers not using a customer version will automatically switch to a new version when the environment default is changing.
• Customer configured versions take precedence over environment default versions.
• Note: Notifications are always sent using the Customer specific or environment default version.

Endpoints

• Currently the versions 3.0 and 2.1 are active.
• Additionally currently deprecated versions (1.7.x, 2.0.x) and deprecated endpoints (gi-de domain) are available.
• For details see API References.

API	Production endpoint	Release date	Sandbox endpoint	Release date
eCom Tokenizer API 3.0	https://ecom-tokenizer.epayments.digital/api/v3.0	2024-07-25	https://ecom-tokenizer-pat.epayments.digital/api/v3.0	2024-02-28
eCom Static API 3.0	https://ecom-tokenizer.epayments.digital/static/v3.0	2024-07-25	https://ecom-tokenizer-pat.epayments.digital/static/v3.0	2024-02-28
eCom Tokenizer API 2.1	https://ecom-tokenizer.epayments.digital/api/v2.1	2024-02-15	https://ecom-tokenizer-pat.epayments.digital/api/v2.1	2024-02-14
eCom Static API 2.1	https://ecom-tokenizer.epayments.digital/static/v2.1	2024-02-15	https://ecom-tokenizer-pat.epayments.digital/static/v2.1	2024-02-14

Error handling

The tokenizer API follows RPC style. It does not use extensively HTTP error codes to express error scenarios, especially not business logic errors.

• Most of the error cases are responded with HTTP 200.
• All the negative responses that come with HTTP 200 are considered to be non-recoverable.
• Some error scenarios are expressed with HTTP 503. The HTTP 503 response body follows the same schema as the HTTP 200 error messages. But the requests that result in HTTP 503 may get automatically resolved when retrying the same request with a certain retry strategy.
• A client application can rely on the code 503 to schedule automatic retries. The HTTP 200 negative responses assume that the problem can only be solved using manual intervention, either on the caller or on the recipient side.

Instead of using HTTP codes to express business and technical errors, the tokenizer API uses two fields in the response JSON message. The "statusCode" field is an enumerated value, that categorizes the error scenario. The "errorMessage" field provides some more background information about the failure. The same two fields are used in both HTTP 200 and 503 responses.

Note

• All statusCodes besides from OK are considered to be business error situations, which require further investigation.
• The "statusCodes" listed below are continuously going to evolve. G+D will keep improving the error information for better troubleshooting.
• Do not build business logic that relies on statusCodes. Log them only, and use them for manual troubleshooting.
• Rely on the HTTP 503 to schedule automatic retries.

HTTP codes

The eCOM Tokenizer uses the following HTTP codes:

HTTP code	Use case	Recoverable
200	HTTP call was successful and a positive response was sent	false
200	HTTP call resulted either in a business error, configuration error, input validation error, non-recoverable system error or non-recoverable TSP error. Instead of using a HTTP status code, the error scenario is expressed with a statusCode in the JSON response. Additionally, the errorMessage field provides further details.	false
503	HTTP call resulted in an internal or TSP-related error, that may be solved by retrying the request. The caller is invited for retrying the call. The error scenario is expressed with the statusCode and errorMessage fields.	true

HTTP codes for static data

For static data, like metadata or images the codes are extended by:

HTTP code	Use case	Recoverable
200	HTTP call was successful and a positive response was sent	false
400	HTTP request contained invalid data and failed at validation level.	false
404	HTTP request arrived at a wrong URI. This error typically happens when requesting non-existing static data.	false
500	HTTP call resulted either in a business error, configuration error, input validation error, non-recoverable system error or non-recoverable TSP error.	false
503	HTTP call resulted in an internal or TSP-related error, that may be solved by retrying the request. The caller is invited for retrying the call.	true

Error codes

Generic errors
statusCode	errorMessage	description	recoverable
BAD_REQUEST	(Output of the input message validator)	Used to express input validation problems	no
SERVICE_ERROR	Failed to process request, please contact G+D	An internal error happened that most likely need manual intervention to fix	no
TEMPORARY_SERVICE_ERROR	Failed to process request, try again later	An internal error happened, that may be solved by retrying the request	yes
SERVICE_CONFIGURATION_ERROR	Configuration failure, please contact G+D	There is missing configuration for the current Token Requestor. Manual intervention is necessary to fix it.	no
NOT_SUPPORTED	The service {} is not supported by card scheme {}	An API was called that is not supported by the TSP	no
PAYMENT_APP_NOT_FOUND_ERROR	Payment app not found	The specified payment app is not existing. Manual intervention is necessary to fix it.	no
TOKEN_NOT_FOUND	Token not found	An unknown token reference was in the API request	no
CRYPTOGRAPHY_ERROR	(Error detail)	A cryptographic operation failed when processing the request. E.g. JWE decryption failed, unupported algorithm was used, ...	no
MISSING_REQUEST_ID	<EMPTY>	No gd-request-id HTTP header was added to the request	no
MULTIPLE_REQUEST_IDS	<EMPTY>	Multiple gd-request-id HTTP headers were added to the request	no
INVALID_CUSTOMER_ID	Missing customer identifier header Multiple customer identifier headers The Common Name (CN) 'xxx' of the TLS client certificate is unknown	The customer ID of the common name of the TLS certificate is invalid for the current api call.	no
UNHANDLED	Failed to process request, please contact G+D	An unexpected error happened. Fixing needs manual intervention	no
AUTHORIZE_ERROR	Not authorized to perform the operation.	The customer is not authorized to execute the requested operation. DEPRECATED: this error code will be removed in the next release (2023-06-22).	no
Generic TSP errors
statusCode	errorMessage	description	recoverable
TSP_SERVICE_ERROR	Communication error with tsp	A problem occured during the call to TSP, that is assumed to be non-retriable	no
TSP_TEMPORARY_SERVICE_ERROR	Communication error with tsp. Please retry the request.	A problem occured during the call to TSP, a retry may resolve it	yes
TSP_UNKNOWN_ERROR	(Detailed error message)	Unexpected error happened during the TSP call	no
VTS specific errors
Note As of version 2.0.0, the TSP specific error codes, including onboarding, have changed fundamentally to provide a better harmonization. Please move to section Error handling V2 for TSP specific errors if you are looking to upgrade to current version 2.1.x or higher or are just starting to integrate with G+D.
The error messages contain the messages returned by VTS. Several of these error cases indicate errors to that the customer has no impact, and can only be resolved between G+D and Visa. We provide these error information for the sake of transparency.
statusCode	errorMessage	description	recoverable
VTS_INVALID_PARAMETER	(VTS error message)	VTS considered some input parameter is invalid	no
VTS_INVALID_REQUEST	(VTS error message)	Invalid request for VTS DEPRECATED: this internal error code will be replaced by SERVICE_ERROR at 2023-06-22.	no
VTS_CONFIGURATION_ERROR	(VTS error message)	VTS has incorrect configuration	no
VTS_AUTHENTICATION_ERROR	(VTS error message)	VTS could not authenticate the request	no
VTS_CARD_VERIFICATION_ERROR	(VTS error message)	The provided card verification code is incorrect	no
VTS_CARD_NOT_ELIGIBLE	(VTS error message)	The provided card is not eligible	no
VTS_PROVISION_DATA_EXPIRED	(VTS error message)	The JWE-encrypted data sent to VTS exceeded its validity period DEPRECATED: this internal error code will be replaced by SERVICE_ERROR at 2023-06-22.	no
VTS_CARD_NOT_ALLOWED	(VTS error message)	The requested operation was rejected, the error message may provide the reason.	no
VTS_DECLINED	(VTS error message)	The requested operation was rejected, the error message may provide the reason.	no
VTS_NOT_ALLOWED	(VTS error message)	The requested operation was rejected, the error message may provide the reason.	no
Mastercard specific errors
The error messages contain the messages returned by MC. Several of these error cases indicate errors to that the customer has no impact, and can only be resolved between G+D and Mastercard. We provide these error information for the sake of transparency.
statusCode	errorMessage	description	recoverable
MCSCOF_BAD_REQUEST_ERROR	(MC error message)	Mastercard detected an error in the incoming request	no
MCSCOF_UNAUTHORIZED	(MC error message)	Mastercard was called without a proper access token	no
MCSCOF_FORBIDDEN	(MC error message)	Mastercard was called without permissions	no
MCSCOF_NOT_FOUND	(MC error message)	The requested URL does not exist	no
MCSCOF_INTERNAL_SERVER_ERROR	(MC error message)	Mastercard internal server error	no
MCSCOF_TEMPORARY_FORBIDDEN	(MC error message)	Call to Mastercard is temporary forbidden	yes
MCSCOF_TEMPORARY_INTERNAL_SERVER_ERROR	(MC error message)	Mastercard is temporary not working	yes
MCSCOF_TEMPORARY_RATE_LIMIT_EXCEEDED	(MC error message)	Rate limit is temporarioly exceeded	yes
Onboarding errors
statusCode	errorMessage	description	recoverable
VTS_ONBOARDING_VALIDATION_FAILED		VTS found some input field as invalid. Unfortunately very often the concrete error is not disclosed, and the case has to be clarified via emails.	no
VTS_ONBOARDING_TR_ALREADY_ONBOARDED		The given Token Requestor is already onboarded to VTS. This error is returned from the eCom Tokenizer.	no
MCSCOF_ONBOARD_TR_NOT_FOUND		The requested Token Requestor does not exist	no
MCSCOF_OFF_BOARD_TR_NOT_ONBOARDED		The given Token Requestor is not onboarded	no
Bulk Tokenize errors
Job level errors (Bulk tokenization)
statusCode	errorMessage	description	recoverable
BAD_REQUEST	(Output of the input message validator)	Used to express input validation problems	no
DUPLICATE_JOB_ID	TokenBulkJob with <jobId> is already submitted.	TokenizeBulk JobIDs must be unique	no
JOB_NOT_FOUND_ERROR	TokenBulkJob <jobId> not found.	TokenizeBulk Job with given jobId was not found	no
SERVICE_ERROR	Failed to process request, please contact G+D	An internal error happened when submitting the job or requesting the results. Most likely manual intervention is needed to fix the issue.	no
SERVICE_CONFIGURATION_ERROR	Configuration failure, please contact G+D	There is missing configuration for the current Customer. Manual intervention is necessary to fix it.	no
UNHANDLED	Failed to process request, please contact G+D	An unexpected error happened. Fixing needs manual intervention	no
Generic Funding Account Row level errors (Bulk tokenization)
BAD_REQUEST	(Output of the input message validator)	Used to express input validation problems for the Funding Account Row	no
CRYPTOGRAPHY_ERROR	(Output of the input message validator)	A cryptographic operation failed when processing the Funding Account Row. E.g. JWE decryption failed, unupported algorithm was used, ...	no
SERVICE_ERROR	Failed to process request, please contact G+D	An internal error happened when processing the Funding Account Row. Most likely manual intervention is needed to fix the issue.	no
SERVICE_CONFIGURATION_ERROR	Configuration failure, please contact G+D	There is missing configuration for the Token Requestor / Payment Application of Funding Account Row. Manual intervention is necessary to fix it.	no
BULK_JOB_PROCESSING_ERROR	Internal TokenBulkJob processing error, please contact G+D / More detailed error message if available	An internal error specific to Bulk Tokenization happened when processing the Funding Account Row. Manual intervention is necessary to fix it.	no
PAYMENT_APP_NOT_FOUND_ERROR	Payment app not found	The specified payment app is not existing. Manual intervention is necessary to fix it.	no
TSP_SERVICE_ERROR		A problem occurred during the call to TSP when processing the Funding Account Row, that is assumed to be non-retriable	no
TSP_TEMPORARY_SERVICE_ERROR		A problem occurred during the call to TSP when processing the Funding Account Row, a retry may resolve it	yes
TSP_UNKNOWN_ERROR		Unexpected error happened during the TSP call when processing the Funding Account Row	no
VISA specific Funding Account Row level errors (Bulk tokenization)
VTS_INVALID_PARAMETER	(VTS error message)	VTS considered some input parameter is invalid	no
VTS_INVALID_REQUEST	(VTS error message)	Invalid request for VTS DEPRECATED: this internal error code will be replaced by SERVICE_ERROR at 2023-06-22.	no
VTS_CONFIGURATION_ERROR	(VTS error message)	VTS has incorrect configuration	no
VTS_AUTHENTICATION_ERROR	(VTS error message)	VTS could not authenticate the request	no
VTS_CARD_VERIFICATION_ERROR	(VTS error message)	The provided card verification code is incorrect	no
VTS_CARD_NOT_ELIGIBLE	(VTS error message)	The provided card is not eligible	no
VTS_PROVISION_DATA_EXPIRED	(VTS error message)	The JWE-encrypted data sent to VTS exceeded its validity period DEPRECATED: this internal error code will be replaced by SERVICE_ERROR at 2023-06-22.	no
VTS_CARD_NOT_ALLOWED	(VTS error message)	The requested operation was rejected, the error message may provide the reason.	no
VTS_DECLINED	(VTS error message)	The requested operation was rejected, the error message may provide the reason.	no
VTS_NOT_ALLOWED	(VTS error message)	The requested operation was rejected, the error message may provide the reason.	no
MASTERCARD specific Funding Account Row level errors (Bulk tokenization)
MCSCOF_BAD_REQUEST_ERROR	(MC error message)	Mastercard detected an error in the incoming request	no
MCSCOF_UNAUTHORIZED	(MC error message)	Mastercard was called without a proper access token	no
MCSCOF_FORBIDDEN	(MC error message)	Mastercard was called without permissions	no
MCSCOF_NOT_FOUND	(MC error message)	The requested URL does not exist	no
MCSCOF_INTERNAL_SERVER_ERROR	(MC error message)	Mastercard internal server error	no
MCSCOF_TEMPORARY_INTERNAL_SERVER_ERROR	(MC error message)	Mastercard is temporary not working	yes
MCSCOF_TEMPORARY_FORBIDDEN	(MC error message)	Call to Mastercard is temporary forbidden	yes
MCSCOF_TEMPORARY_RATE_LIMIT_EXCEEDED	(MC error message)	Rate limit is temporarioly exceeded	yes

Error handling V2

The eCOM Tokenizer API version 2.0.0 will introduce an improved error handling. The goals of the improvement are the following

• Abstraction of the network TSP scheme specific statusCodes
• Providing network TSP scheme independent statusCodes
• Note on statusCode values, harmonization and usage
  • Simplification for integrators (merchants/PSPs) to choose the best possible appropriate next actions such as retry, continue with FPAN, cardholder feedback etc.
  • Improving troubleshooting measures and error statistic monitoring
  • All statusCodes besides from OK are considered to be business error situations, which require further investigation.
  • The "statusCodes" listed below are continuously going to evolve. G+D will keep improving the error information for better troubleshooting.
  • Do not build business logic that relies on statusCodes. Log them only, and use them for manual troubleshooting.
  • Rely on the HTTP 503 to schedule automatic retries.
  • With version 3.0.0 ELO payment scheme is supported, providing the same error codes as listed below for MCSCOF and VTS

The Generic Errors remain the same as before. In contrast, the Generic TSP errors, VTS specific errors and Mastercard specific errors will be merged into the following generic statusCodes:

new statusCode	old statusCode	API	description	recoverable
TSP_INVALID_CARD_DATA	VTS_INVALID_PARAMETER VTS_CARD_VERIFICATION_ERROR MCSCOF_BAD_REQUEST_ERROR	/tokenize, /tokenize-bulk, /tokenize-bulk-multi-scheme	One or more elements of the funding account card data (FPAN, expiration date, CVV) provided is considered to be invalid by either the network TSP or the issuer. E.g. expired card, too short FPAN, wrong CVV code.	no
TSP_CARD_NOT_ELIGIBLE	VTS_CARD_NOT_ELIGIBLE MCSCOF_BAD_REQUEST_ERROR	/tokenize, /tokenize-bulk, /tokenize-bulk-multi-scheme	The funding account card data (FPAN, expiration date, CVV) provided is correct, but the funding account card as such (BIN range) is not eligible for tokenization.	no
TSP_ISSUER_DECLINED	VTS_DECLINED MCSCOF_BAD_REQUEST_ERROR	/tokenize, /tokenize-bulk, /tokenize-bulk-multi-scheme	The funding account card data (FPAN, expiration date, CVV) provided by the cardholder is correct, but the issuing bank rejected the tokenization request. The reason may be e.g. the outcome of risk evaluation.	no
TSP_OPERATION_NOT_ALLOWED	VTS_NOT_ALLOWED MCSCOF_BAD_REQUEST_ERROR	All	The requested operation was rejected by the network scheme. The reason may be that the status of the token is not active or no further actions with the card are allowed.	no
TSP_BAD_REQUEST	MCSCOF_BAD_REQUEST_ERROR	All	The request contains invalid input parameters other than the funding account card data. Additional error message explanations: Unsupported token. Can occur during VISA tokenization. An unsupported token type has been sent to VISA, which the issuer is not configured to handle. For example, a token instead of a PAN has been sent. Invalid source token. Can occur during VISA tokenization. Incorrect PAN data was sent and therefore the token retrieval failed on VISA side.	no
TSP_SERVICE_ERROR	TSP_SERVICE_ERROR VTS_CONFIGURATION_ERROR VTS_AUTHENTICATION_ERROR MCSCOF_UNAUTHORIZED MCSCOF_FORBIDDEN MCSCOF_NOT_FOUND	All	The request sent by eCOM Tokenizer to the network TSP failed because of a technical reason. The problem typically happens when the network TSP itself reports and unknown internal failure. It is not expected that an automatic retry will solve the problem in short time. However, a retry scheduled at a later point in time may succeed. Additional error message explanations: No CVV2 Key. Can occur during VISA tokenization. The CVV2 Key for the card has not been configured on VISA side by the issuer.	no
TSP_TEMPORARY_SERVICE_ERROR	TSP_TEMPORARY_SERVICE_ERROR MCSCOF_INTERNAL_SERVER_ERROR MCSCOF_TEMPORARY_FORBIDDEN MCSCOF_TEMPORARY_INTERNAL_SERVER_ERROR MCSCOF_TEMPORARY_RATE_LIMIT_EXCEEDED	All	The request sent by eCOM Tokenizer to the network TSP failed because of a technical reason. Such a reason can be an instantaneous network connectivity problem. A retry within short time may solve the problem.	yes
TSP_UNKNOWN_ERROR	TSP_UNKNOWN_ERROR VTS_INVALID_PARAMETER MCSCOF_BAD_REQUEST_ERROR	All	eCOM Tokenizer's requests to network TSP systems can rarely be rejected for unexpected/undocumented reasons.	no

Notes

• All the TSP_errors are applicable for those cases, when the eCOM Tokenizer initiated an HTTPS call to the network TSP, but the call failed for a technical or business reason. In contrast, the existing Generic errors identify such error cases that originate from the eCOM Tokenizer, before even calling a network TSP. In rare cases these validated requests still fail on the network schemes. For these cases the same TSP_BAD_REQUEST code is used.
• The same changes apply to bulk tokenization, although the bulk APIs have also a separate set of specific error codes. The Job level errors (Bulk tokenization) and Generic Funding Account Row level errors (Bulk tokenization) stay the same, but the VISA specific Funding Account Row level errors (Bulk tokenization) and MASTERCARD specific Funding Account Row level errors (Bulk tokenization) are replaced with the same statusCodes as seen above.
• Some of the old statusCodes are mapped to multiple new statusCodes. E.g. MCSCOF_BAD_REQUEST_ERROR or VTS_INVALID_PARAMETER. The reason is that these old statusCodes were too generic and have covered multiple different semantics.
• Similarly, there are old statusCodes that have been merged to a single one. E.g. VTS_CONFIGURATION_ERROR or VTS_AUTHENTICATION_ERROR. These old statusCodes were too specific and described error scenarios that did not require special treatment on customer side. These errors are only relevant between the eCOM Tokenizer and the network TSPs and typically indicate problems at the time of integration other than normal operational problems.
• Error messages for TSP_ statusCodes
  The previous sections explained the new statusCode handling. Additionally to statusCode, the error response JSON messages also contain a field called errorMessage. This remains a freetext field that must not be parsed and used for business logic.
  In case of TSP errors, it will be prefixed with "tspMessage:" and it will contain freetext error information that originates from the TSP. This freetext message can be changed anytime by the network TSPs. It may also contain information that has no meaning or no relevance for eCOM Tokenizer customers. However, there may be cases when it can facilitate the troubleshooting.
  Example errorMessages:
  
  • tspMessage: Visa declined this API request. If you see this too frequently and you think you are getting this in error. Contact the bank to resolve the issue.
  • tspMessage: Further operations are no longer allowed. Please contact your bank to resolve the issue.
  • tspMessage: Request cannot be executed due to the incorrect field value. Tokenization request was declined by Issuer.

TSP onboarding errors

The above changes apply to the APIs except Onboarding. The Onboarding API has the following additional statusCodes. The semantic of these error codes doesn't change, only the names are made generic and applicable for multiple network TSPs.

statusCode API 2.x and following	statusCode API 1.x	API	description	recoverable
TR_VALIDATION_FAILED	VTS_ONBOARDING_VALIDATION_FAILED	/onboard-to-vts	VTS found some input field as invalid. Unfortunately very often the concrete error is not disclosed and the case has to be clarified via Service Support	no
TR_ALREADY_ONBOARDED	VTS_ONBOARDING_TR_ALREADY_ONBOARDED	/onboard-to-vts	The given Token Requestor is already onboarded to VTS. This error is returned from the eCom Tokenizer. Important note VISA gives some high importance to the URL of the Token Requestor's (merchant’s) website related to the payment transaction. See parameter primaryWebsiteUrl inside request OnboardToVtsRequest->address element. It should include "https://". An example: https://www.merchant.com Visa uses the value as "primary identifier" for a Token Requestor (TR)! I.e. in case the exact value is sent again, no matter if the values of all other parameters are different, Visa considers the TR as already onboarded and returns the same response values as for the onboarding request where this primaryWebsiteUrl was used before. In consequence, the eCOM Tokenizer also returns the same values as before! In addition, the statusCode "TR_ALREADY_ONBOARDED" is returned If the TR is a franchise and wished to be onboarded separately, the URL has to be extended with a different identifier. Examples: https://www.franchisemerchant.com/munich, https://www.franchisemerchant.com/berlin	no
TR_ALREADY_ONBOARDED	n/a	/onboard-to-elo	The given Token Requestor is already onboarded to ELO. This error is returned from the eCom Tokenizer.	no
TR_NOT_FOUND	MCSCOF_ONBOARD_TR_NOT_FOUND	/onboard-to-mc-status	The requested Token Requestor does not exist	no
TR_NOT_ONBOARDED	MCSCOF_OFF_BOARD_TR_NOT_ONBOARDED	/offboard-from-mc	The given Token Requestor is not onboarded	no

Renamed statusCodes

There are a few statusCodes that keep their original meaning, but have got more suitable names:

new statusCode	old statusCode
PAYMENT_APP_NOT_FOUND	PAYMENT_APP_NOT_FOUND_ERROR
UNKNOWN_ERROR	UNHANDLED
JOB_DUPLICATE_ID	DUPLICATE_JOB_ID
JOB_NOT_FOUND	JOB_NOT_FOUND_ERROR
JOB_PROCESSING_ERROR	BULK_JOB_PROCESSING_ERROR

All V2 statusCodes

The following table summarizes the statusCodes that will be supported after the improvement:

statusCode	API	errorMessage*	description	recoverable
BAD_REQUEST	All	<Output of the input message validator>	Used to express input validation problems	no
SERVICE_ERROR	All	Failed to process request, please contact G+D	An internal error happened that most likely need manual intervention to fix	no
TEMPORARY_SERVICE_ERROR	All	Failed to process request, try again later	An internal error happened, that may be solved by retrying the request	yes
SERVICE_CONFIGURATION_ERROR	All	Configuration failure, please contact G+D	There is missing configuration for the current Token Requestor. Manual intervention is necessary to fix it.	no
NOT_SUPPORTED	All	The service {} is not supported by card scheme {}	An API was called that is not supported by the TSP	no
PAYMENT_APP_NOT_FOUND	All	Payment app not found	The specified payment app is not existing. Manual intervention is necessary to fix it.	no
TOKEN_NOT_FOUND	/suspend, /resume, /delete, /token-info, /transact	Token not found	An unknown token reference was in the API request	no
CRYPTOGRAPHY_ERROR	/tokenize, /tokenize-bulk, /tokenize-bulk-multi-scheme	<Error detail>	A cryptographic operation failed when processing the request. E.g. JWE decryption failed, unupported algorithm was used, ...	no
MISSING_REQUEST_ID	All	<empty>	No gd-request-id HTTP header was added to the request	no
MULTIPLE_REQUEST_IDS	All	<empty>	Multiple gd-request-id HTTP headers were added to the request	no
INVALID_CUSTOMER_ID	All	The Common Name (CN) 'xxx' of the TLS client certificate is unknown	The customer ID of the common name of the TLS certificate is invalid for the current api call.	no
UNKNOWN_ERROR	All	Failed to process request, please contact G+D	An unexpected error happened. Fixing needs manual intervention	no
TSP_INVALID_CARD_DATA	/tokenize, /tokenize-bulk, /tokenize-bulk-multi-scheme	tspMessage: <comma-separated freetext error message from TSP>	One or more elements of the funding account card data (FPAN, expiration date, CVV) provided is considered to be invalid by either the network TSP or the issuer. E.g. expired card, too short FPAN, wrong CVV code.	no
TSP_CARD_NOT_ELIGIBLE	/tokenize, /tokenize-bulk, /tokenize-bulk-multi-scheme	tspMessage: <comma-separated freetext error message from TSP>	The funding account card data (FPAN, expiration date, CVV) provided is correct, but the funding account card as such (BIN range) is not eligible for tokenization.	no
TSP_ISSUER_DECLINED	/tokenize, /tokenize-bulk, /tokenize-bulk-multi-scheme	tspMessage: <comma-separated freetext error message from TSP>	The funding account card data (FPAN, expiration date, CVV) provided by the cardholder is correct, but the issuing bank rejected the tokenization request. The reason may be e.g. the outcome of risk evaluation.	no
TSP_OPERATION_NOT_ALLOWED	/delete, /suspend, /resume, /transact, /token-info	tspMessage: <comma-separated freetext error message from TSP>	The requested operation was rejected by the network scheme. The reason may be that the status of the token is not active.	no
TSP_BAD_REQUEST	All	tspMessage: <comma-separated freetext error message from TSP>	The request contains invalid input parameters other than the funding account card data. Additional error message explanations: Unsupported token. Can occur during VISA tokenization. An unsupported token type has been sent to VISA, which the issuer is not configured to handle. For example, a token instead of a PAN has been sent. Invalid source token. Can occur during VISA tokenization. Incorrect PAN data was sent and therefore the token retrieval failed on VISA side.	no
TSP_SERVICE_ERROR	All	tspMessage: <comma-separated freetext error message from TSP>	The request sent by eCOM Tokenizer to the network TSP failed because of a technical reason. The problem typically happens when the network TSP itself reports and unknown internal failure. It is not expected that an automatic retry will solve the problem in short time. However, a retry scheduled at a later point in time may succeed. Additional error message explanations: No CVV2 Key. Can occur during VISA tokenization. The CVV2 Key for the card has not been configured on VISA side by the issuer.	no
TSP_TEMPORARY_SERVICE_ERROR	All	tspMessage: <comma-separated freetext error message from TSP>	The request sent by eCOM Tokenizer to the network TSP failed because of a technical reason. Such a reason can be an instantaneous network connectivity problem. A retry within short time may solve the problem.	yes
TSP_UNKNOWN_ERROR	All	tspMessage: <comma-separated freetext error message from TSP>	eCOM Tokenizer's requests to network TSP systems can rarely be rejected for unexpected/undocumented reasons.	no
TR_VALIDATION_FAILED	/onboard-to-vts	tspMessage: <comma-separated freetext error message from TSP>	VTS found some input field as invalid. Unfortunately very often the concrete error is not disclosed and the case has to be clarified via Service Support	no
TR_ALREADY_ONBOARDED	/onboard-to-vts, /onboard-to-elo	<empty>	This is not an error scenario. Instead. it can be interpreted as a positive response. It means that the merchant had already been onboarded to VTS or ELO earlier, and the current API call did not have any further contribution.	no
TR_NOT_FOUND	/onboard-to-mc-status	Token requestor not found	The requested Token Requestor does not exist	no
TR_NOT_ONBOARDED	/offboard-from-mc	Token requestor not onboarded	The given Token Requestor is not onboarded	no
JOB_DUPLICATE_ID	/tokenize-bulk, /tokenize-bulk-multi-scheme	TokenBulkJob with <jobId> is already submitted.	TokenizeBulk JobIDs must be unique	no
JOB_NOT_FOUND	/tokenize-bulk-results	TokenBulkJob <jobId> not found.	TokenizeBulk Job with given jobId was not found	no
JOB_PROCESSING_ERROR	/tokenize-bulk, /tokenize-bulk-multi-scheme, /tokenize-bulk-results	Internal TokenBulkJob processing error, please contact G+D / More detailed error message if available	An internal error specific to Bulk Tokenization happened when processing the Funding Account Row. Manual intervention is necessary to fix it.	no

* The final errorMessages might slightly differ from what is shown in this column

Retry handling

The eCom Tokenizer forwards the TSP notifications to the customers. The notifications may fail because of different reasons.

In case the failure is retriable, the eCom Tokenizer schedules automatic retries. Network level errors and HTTP 5xx are considered to be retriable.

• In the first 5 minutes we schedule retries with 1 minute intervals. This may solve short term outages.
• After 5 minutes we schedule 3 more retries with 15min, 30min and 2h intervals. This may solve longer outages or planned maintenance.
• We honor the HTTP 503 Retry-After header. In case that header is present, eCom Tokenizer will schedule the retry accordingly, and ignores its own retry strategy. However, the maximal overall retry period is 3 hours. Everything beyond that is truncated.

Token Updated Notification - reason handling

The eCOM Tokenizer API version 2.1.0 provides additional information in the Token-Updated notification. These reason codes allow you to identify additional actions that should be performed when this information is received.
Token Lifecycle management notifications are triggered when for example an issuer suspends or unsuspends the card, or issues a new card before expiration, or a cardholder updates the card details.

For such cases you should update the data of your stored objects for the related token with the new status and other parameters that may have changed.
I.e. update the data received in tokenInfo and metadata (identified by a changed metadataId -> you should trigger a get metadata request)

Additionally, an issuer may trigger an account update within the account range or across another account range based on the following events:

• FPAN replacement within the same account range
• FPAN replacement in a different account range
• Card issuing maintenance tasks like for example moving from a 6 to 8-digit BIN. This may result in the token number being changed (even if underlying PAN does not change)
• Token expiry date extension

The TOKEN_REFRESH reason code is provided for such scenarios. It can currently only be expected for Mastercard tokens in one of the above-mentioned events.
TOKEN_REFRESH reason code means, that the token and/or token expiry may have changed. The following actions are required:

• Fetch the new token, token expiry & cryptogram by making a /transact request.
• As for the other codes, you should update your stored objects with the data received in tokenInfo and metadata (identified by a changed metadataId -> you should trigger a get metadata request)

In the case of a Mastercard token and Merchant Initiated Transaction (MIT), when TOKEN_REFRESH is received the subsequent MIT after token_refresh scenario must carry the fresh cryptogram and in addition you should send Security Level Indicator (SLI) value 246.
Subsequent transactions can revert to SLI value 247 and a cryptogram is no longer required.

Below is the list of reason codes and additional information.

Reason Code	Notification Detail Message*	Description	Minimum actions to take
CARD_UPDATED	ACCOUNT_CLOSED, ACCOUNT_UPDATED, Card data updated	This notification reason is received when FPAN related data has changed, or the account was closed.	Update all data received
METADATA_UPDATE	CARD_ART_UPDATE, Metadata updated	This notification reason is received when FPAN metadata has changed.	Update all data received
TOKEN_STATUS_CHANGED	DEVICE_LOST, DEVICE_FOUND, DEVICE_STOLEN, FRAUD_SUSPECTED, FRAUD_MITIGATED, OTHER, Token status updated	This notification reason is received when the token status has changed due to some life-cycle scenarios.	Update all data received
TOKEN_REFRESH	TOKEN_REFRESH	This notification reason is received when the whole token and/or token expiry has changed.	Update all data received, Request a new cryptogram to receive the new token from the TSPs

* The notification detail messages might slightly differ from what is shown in this column depending on data sent by the TSPs

UC 1: Tokenization of single FPAN

This use case is for tokenizing a single FPAN, for example during account registration or as part of the checkout process.
Another important use case is “Push Provisioning”, where the end user is initiating the tokenization process by pushing the provisioning request for example from its issuer mobile banking app to the merchant app.
It can also be used for an FPAN stored on file by merchant or PSP, but for this scenario using the bulk tokenization API would be recommended.

Use case is supported by the API: /tokenize

The workflow above contains the alternatives:

• Merchant has FPANs on file and tokenizes them through their PSP
• PSP stores FPANs on behalf of the merchant and provides a proprietary token to the merchant. The network token / token reference stays with the PSP and the merchant can continue using the proprietary token.

In the latter case, the PSP might need to consider upgrading its API with the merchant to enable card metadata information to be passed to the merchant. For example, to show last four digits of FPAN or card art image to the end user. The PSP could also replace proprietary tokens with network tokens at the merchant.

UC2: Tokenization in bulk

This use case is dedicated to efficiently tokenize existing cards on file. Bulk tokenization allows large numbers of stored cards to be assigned a network token performing this in batches, rather than individually. As more and more issuers gradually support tokenization, the hit rates will grow.

Use case is supported by the API: /tokenize-bulk

Please note that ELO Bulk tokenization is not yet supported.

UC3: Transact with token

Transacting with network tokens consists of preparing the payment data (like amount, currency, date, time) and additionally requesting a cryptogram. Once the cryptogram is provided by eCOM Tokenizer together with the token, the final transaction authori-zation request can be constructed and sent to the card scheme network as usual.

Use case is supported by the API: /transact

UC4: Token life cycle management

This use case contains token life cycle management actions triggered either by the end user on the eCommerce web shop or by the eCommerce merchant (e.g. deleting obsolete tokens for users that have stopped using the service).

Token life cycle management scenarios are:

• Token Suspension - not suppored by TSP APIs
• Token Resumption - not suppored by TSP APIs
• Token Deletion

Use case supported by the API: /delete

UC5: Token life cycle notifications

Cardholders can interact multiple ways with their card issuers that result in life cycle events to the ecosystem. The sequence diagram below covers a few typical cases:

• The contract with the issuer is terminated rendering all cards and related tokens invalid -> tokens are terminated
• User reports card lost or stolen or damaged -> issuer issues a new card -> tokens stay intact but the related FPAN data e.g. last four digits might change
• Funding card expires -> issuer procures a new card. Tokens stay intact and Token Requestors (TRs) are notified on the new funding card expiry date
• The end user triggers token status life cycle management actions from issuer side (e.g. issuer mobile banking application)

Use cases are supported by the API:

• /token-updated-event
• /metadata-updated-event

UC6: Merchant onboarding

The Onboarding APIs published by the Network TSPs vary widely. I.e. the data elements required, the supported functions and the technical implementation differ significantly. For this reason the eCOM Tokenizer publishes separate endpoints per card scheme. It has to be noted, that the Onboarding APIs main purpose is to enable PSPs to onboard direct merchants. Ideally all direct merchants should get their own Token Requestor ID (TRID) assigned. For onboarding other merchant entities such as marketplaces, franchise business or small sellers with a small yearly payment volume please reach out to your G+D contact. More details you find also in the FAQs.

UC6.1: VTS onboarding

VTS implements a synchronous Onboarding API. In each OnboardToVtsRequest call a single merchant is onboarded. The merchant data has to include at least the mandatory parameters of the OpenAPI spec. The tspId has to be "VTS_SANDBOX" in the test environment, and "VTS" in production.

Note VTS onboard API is immutable. After a merchant has been once onboarded to VTS, onboard data cannot be changed and new payment applications cannot be added. Therefore, when calling the /onboard-to-vts API, it is possible that the number of requested payment applications and the defined vtsClientAppId and vtsProfileName values do not match with the response. What can be guaranteed, is that the response will always contain at least one VtsPaymentApplication which can be used in TokenizeRequests and other API calls.

The merchant is identified either by

• businessIdentificationType and businessIdentificationValue
• acquirerId and acquirerMerchantId

The businessIdentificationType can be one of the following:

Business Identification Type	Business Identification Value Description
ABN	Australian business number Format: 11 numeric digits
ACN	Australian company number Format: 9 numeric digits
BID	Business identification number; all countries. Format: 8 numeric digits Note: You must contact your Visa representative before using BID for businessIdentificationType
BIN	Kazakhstan business identification number Format: 12 numeric digits
BIR	Philippines certificate of registration Format: 12 numeric digits; hyphen-separated Example: 123-456-789-012
BN	Canadian business number Format: 9 numeric digits
BRN	South Korea business registration number Format: 10 numeric digits; hyphen-separated Example: 123-45-67890
BRNO	Malaysia only Format: Up to 10 numeric digits followed by a hyphen and a single character or 12 numeric digits. Example: 123456789012
CL	Commercial License Number, Qatar Format: 4–6 numeric digits
CLN	Company License Number, Kuwait Format: 5–7 numeric digits
CORPORATE_NUMBER	Corporate Number, Japan Format: 13 numeric digits; leading digit is a non-zero check digit for the following 12 digits
CNPJ	Brazil only Format: 14 alphanumeric characters, identified by n in the example, and punctuation characters (period, slash, and hyphen). Example: nn.nnn.nnn/nnnn-nn
CR	Company Registration Number, Saudi Arabia Format: 10–12 numeric digits
CUIT	Argentina only Format: 11 numeric digits
EDRPOU	Ukraine Ukrainian corporations: 8 numeric digits Ukrainian individual entrepeneurs: 10 numeric digits
EIN	US Federal tax ID (US only) Format: 9 numeric digits
HKBR	Hong Kong only Format: 11 numeric digits and a hyphen Note: Use 000 if the digits after the hyphen are not specified. Example: 12345678-123
INI	Andorran General Indirect Tax Format: 8 alphanumeric characters; the first and last characters must be alphabetic.
NATIONAL_ID	Dominican Republic (DO) Cedula de Identidad (Merchant Owner ID) Format: DO + 11 digits Example: DO01234567890
NIB	Indonesia business identification number Format: 13 numeric digits
NID	South Africa national identification number Format: 13 numeric digits
NZBN	New Zealand business number Format: 13 numeric digits
PAN	Indian business identification number Format: 10 alphanumeric characters
PAN	Belarus payer account number Format: 9 numeric digits
RFC	Mexico only Format: 12 alphanumeric characters for corporations; 13 alphanumeric characters for individuals.
RNC	Dominican Republic (DO) Registro Nacional de Contribuyentes (National Contributors Number) Format: DO + 9 digits Example: DO123456789
RUC	Peru only Format: 11 numeric digits
RUT	Chile and Columbia only Format: 9 numeric digits; for Chile; 10 numeric digits for Columbia
SIN	Canadian social insurance number Format: 9 numeric digits
SSN	US social security number (US only) Format: 9 numeric digits
TC	Vietnam tax code Format: 10 or 13 numeric digits
UEN	Singapore only Format: 9 or 10 alphanumeric characters
USCI	China united social credit code Format: 18 alphanumeric characters
VAT	Austria, Belgium, Bulgaria, Croatia, Czech Republic, Denmark, Estonia, Finland, Faroe Islands, France, Germany, Greece, Hungary, Iceland, Ireland, Isle of Man, Israel, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Republic of Cyprus, Romania, Saudi Arabia, Slovak Republic, Slovenia, South Africa, Spain, Sweden, Switzerland, Thailand, Turkey, Ukraine, United Arab Emirates, United Kingdom See the formats below.

VAT countries and formats:

Country / Code	VAT Value Format	Example
Austria / AT	AT + 9 characters in which the first character is always a 'U'	ATU12345678
Belgium / BE	BE + 10 characters. Prefix with zero ‘0’ if the customer provides a 9 digit VAT number.	BE1234567890
Bulgaria / BG	BG + 9 or 10 characters	BG123456789 or BG0123456789
Croatia / HR	HR + 11 characters.	HR01234567891
Cyprus / CY	CY + 9 characters; the last character must always be a letter.	CY12345678X
Czech Republic / CZ	CZ + 8, 9 or 10 characters.	CZ12345678, CZ123456789, or CZ0123456789
Denmark / DK	DK + 8 characters	DK12345678
Estonia / EE	EE + 9 characters	EE123456789
Finland / FI	FI + 8 characters	FI12345678
France / FR	FR + 11 characters	FR12345678901
Germany / DE	DE + 9 characters	DE123456789
Greece / EL	EL + 9 characters	EL123456789
Hungary / HU	HU + 8 characters	HU12345678
Iceland / IS	5 or 6 characters	12345
Ireland / IE	IE + 8 numeric or alphabetic characters	IE1234567X
Israel / IL	9 numeric digits	123456789
Isle of Man / GB	GB + 9 or 12 digits; first 2 digits must be 00	GB003456789
Italy / IT	IT + 11 characters	IT12345678901
Latvia / LV	LV + 11 characters	LV12345678901
Lithuania / LT	LT + 9 or 12 characters	LT123456789 or LT123456789012
Luxembourg / LU	LU + 8 characters	LU12345678
Malta / MT	MT + 8 characters	MT12345678
Netherlands / NL	NL + 12 characters of which the tenth character is always B.	NL123456789B01
Norway / NO	NO + 9 digits and the letters + MVA	NO123456789MVA
Poland / PL	PL + 10 alphanumeric characters	PL1234567890
Portugal / PT	PT + 9 characters	PT123456789
Republic of Cyprus / CY	CY + 9 characters. The last character must always be a letter.	CY12345678X
Romania / RO	RO + 2 to 10 characters.	RO12, RO123, RO1234, RO12345, RO123456, RO1234567, RO12345678, RO123456789, or RO1234567890
Saudi Arabia / SA	15 numeric digits	123456789012345
Slovak Republic / SK	SK + 10 characters	SK1234567890
Slovenia / SI	SI + 8 characters	SI12345678
South Africa / ZA	10 or 11 digits	1234567890 or 12345678901
Spain / ES	ES + 9 numeric digits	ES123456789
Sweden / SE	SE + 12 digits	SE123456789012
Switzerland / CH	CH + 9 digits + MWST (german part), TVA (french part), or IVA (italian part)	CH123456789MWST, CH123456789TVA, or CH123456789IVA
Thailand	13 numeric digits	1234567890123
Turkey / TR	TR + 10 characters	TR1234567890
Ukraine / UA	9 or 12 digits	123456789 or 123456789012
United Arab Emirates / AE	15 digits	123456789012345
United Kingdom / GB	GB + 9 digits	GB123456789

The merchant may have multiple payment applications, like a Web App and an Android App. VTS mandates registering at least one payment app. The merchant may decide to register more, but that is optional. VTS expects the following payment app data:

• vtsClientAppId: The branded name of the payment app
• vtsProfileName: The profile name under that the payment app is registered in VTS. It can be identical to vtsClientAppId

Once the merchant and the payment app(s) are onboarded, the VTS API does not give any possibility to update, delete the data. The onboarded merchant cannot be used immediately. The Token Requestor ID assigned to the merchant needs to propagate to all VTS systems and it takes time. Visa suggests waiting 72 hours before allowing tokenizations in the productive environment. In the test environment, the merchant can be used right after onboarding.

The OnboardToVtsResponse response message contains the G+D generated identifiers gdTokenRequestorId and gdPaymentAppIds, that have to be kept persisted, as they are needed for further use cases.

UC6.2: Mastercard onboarding

Mastercard implements an asynchronous Onboarding API. The OnboardToMcRequest contains the data of a single merchant, and one or more payment applications. Similarly to VTS, the merchant has to include at least one payment app in the request. But it also can include multiple or all of them. The tspId has to be "MCSCOF_SANDBOX" in the test environment, and "MC" in production.

In the OnboardToMcRequest the programName identifies the merchant, and the dpaName identifies a single payment app. DPA stands for Digital Payment Application, and it is a term the Mastercard API uses.

The synchronous OnboardToMcResponse contains the G+D generated gdTokenRequestorId and gdPaymentAppIds. The merchant and the payment apps are not yet onboarded at this moment to Mastercard. Mastercard has an asynchronous API, for this reason the onboardStatus will likely be IN_PROGRESS in the synchronous response. The merchant/PSP has to poll for the final response by periodically calling the OnboardToMcStatus API. This call returns the same OnboardToMcResponse response, but ultimately it will show onboardStatus COMPLETED or FAILED. When providing multiple payment apps, a partial success is possible: some apps may get onboarded, others may fail. The Mastercard Onboarding API works more on the payment app basis than merchants basis. What we onboard are in fact the payment apps.

Mastercard supports the update of payment applications. The update feature mainly means adding new payment applications. There are only very few data fields that are updatable for an existing, already onboarded payment application. An update can be triggered by sending the same OnboardToMcRequest request. In case this request contains an already known programName, it is automatically an update request. If there is an already existing dpaName under the known programName, then the matching payment app will get updated. As earlier mentioned, only a few payment app fields are updatable. If there is a new dpaName under an existing programName, then the new payment app will be onboarded to Mastercard.

Note For equality comparison, ProgramName and DpaName considered case-insensitive.

It is possible to off-board payment applications, by sending an OffboardFromMcRequest. As a result, the payment apps with the given dpaNames will be removed from the merchant with the given programName. This call is the same way asynchronous like the OnboardToMcRequest. The result can be periodically polled by using OnboardToMcRequest.

UC6.3: Elo onboarding

Elo implements a synchronous API, similar to VTS. The OnboardToEloRequest contains the data of a single merchant. Contrary to Mastercard and Visa, no separate payment application details need to be provided for Elo. However, a gdPaymentAppId can be provided or will be generated by eCOM accordingly. The tspId has to be "ELO_SANDBOX" in the test environment. Production tspId will be provided once released.

Note Elo onboard API is currently immutable. After a merchant has been once onboarded to Elo, onboard data cannot be changed via the API. If merchant data needs to change, please contact G+D.

In the OnboardToEloRequest the legalId and legalName identify the merchant explicitly and uniquely. The legalId, in this case CNPJ, should be provided without any punctuation. Instead of '52.796.626/0001-50', the submitted legalId should look like this: '52796626000150'

The OnboardToEloResponse contains the G+D generated gdTokenRequestorId and gdPaymentAppId. The merchant is onboarded at this point in time, depending on Elo's processing however, might not be immediately available after the onboarding.

UC7: Fetching data of token

Sometimes the PSP or merchant may need to fetch up to date information for a specific token. The sequence diagram below shows a high level flow diagram of this use case.

Use case is supported by the API: /tokenInfo

Network Level Security

The eCOM Tokenizer API is protected with 2-way-TLS. Only TLS 1.2 or 1.3 are supported, restricted to safe ciphers.

Similarly, the Notification API, that is published by the Customer must also be protected by TLS.

Authentication

The usage of TLS client certificates is mandatory when calling the API, as the client certificate identifies and authenticates the caller. The Common Name of the certificate Subject DN is used as Customer ID.

In case Customer calls the API without a TLS client certificate, or with a wrong TLS client certificate, then the request is responded with HTTP 403.

G+D also uses TLS client certificates when it sends notifications to the Notification API published by the Customer. Customer may decide to implement client certificate check in the Notification API.

Message Level Encryption

Sensitive data must always be encrypted before it is appended to the JSON messages. There can be encrypted data in requests and responses:

• Requests: whenever funding card data (PAN, expiry, CVV2) is sent from Customer to G+D, it has to be encrypted
• Responses: sensitive payment data (cryptogram, token PAN) is sent encrypted from G+D to Customer

The sensitive data is formatted as a small JSON message. In the OpenAPI specification the objects FundingAccountDataPlain and TransactionPayloadPlain describe these sensitive JSON types.

Once the sensitive JSON messages are assembled, they have to get JSON Web Encrypted (JWE), before they are inserted into the top level JSON messages.

JWE

From the list of possible key wrapping ciphers standardized by JSON Web Algorithms (https://datatracker.ietf.org/doc/html/rfc7518) chapter 4.1 we support RSA and EC cipher:

• RSA: RSA-OAEP-256
• EC: ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW

For RSA keys we allow any keys size above or equal to 2048 bits. For EC keys we support all the curves that are mentioned in the RFC, that are currently P-256, P-384, P-521.

From the JWA content encryption algorithms listed in chapter 5.1 of the RFC we support all:

• A128CBC-HS256, A192CBC-HS384, A256CBC-HS512
• A128GCM, A192GCM, A256GCM

During customer onboarding the customer has to choose a pair of JWE key wrapping and content encryption algorithms.

Separate keys are used for encryption in JSON request and JSON responses. In case of requests, G+D possesses the private key and Customer is provided with the public key. In case of responses, it is the opposite way.

The JWE encrypted data has to be compact encoded (dot separated) and added to the top level messages as strings, please see the OpenAPI specification.

The JWE header has to contain the following elements, apart from the mandatory elements as specified by the RFC:

• kid: Key ID that identifies the key used for encryption
• iat: Issued at, a Unix timestamp in seconds since Epoch, that identifies the timestamp when the JWE was generated

Key Exchange

In order to implement the security measures explained above, different key material has to be exchanged between Customer and G+D.

TLS server certificate

Both G+D and Customer have to provide their TLS server certificate chains to each other

TLS client certificate

Acquiring a client certificate can be done in the following way:

• Customer generates an RSA key pair
• Customer wraps the public key into a Certificate Signing Request (CSR). The Common Name (CN) of the certificate should be a Customer ID that G+D provides on beforehand
• Customer sends the CSR to G+D
• G+D signs the certificate and provides it back to the Customer, including the certificate chain until the root

G+D will provide its TLS client certificate chain, that is used for notification sending.

JWE key for requests

Customer chooses between RSA and EC key types. In both cases G+D generates the key pair and shares the public part with Customer. The Key ID is also shared that will be used as "kid" in the JWE header.

JWE key for responses

Customer chooses between RSA and EC key types. In both cases Customer generates the key pair and shares the public part with G+D. The Key ID will be generated and shared by G+D. It will be used as "kid" in the JWE header.

PSD2 impact

PSD2 has impact on the Transact API. The Token Requestor should be able to identify if a certain Payment Transaction falls under PSD2 SCA requirement.

Note In case PSD2 SCA is required, the payment cryptogram has to get "dynamically linked" to the transaction details. In this case the sending of "amount" and "currencyCode" fields in the Transact request is mandatory.

Test Data

In order to test card tokenizations, checkouts and further use cases, the customer should get onboarded to the Visa and Mastercard sandboxes. In case the customer is a PSP, the onboarding has to be done using some test merchant data. Options to onboard a test merchant:

• Merchant data can be provided by the customer and the onboarding can be done by G+D
• Test merchant data can be generated and onboarded by G+D
• Customer can implement the Onboard APIs, and onboard a test merchant programmatically

As result of the merchant onboarding, the customer is given with a gdPaymentAppId per card scheme. These gdPaymentAppIds can be used for API testing. There is also the option to include the gdPaymentAppId during onboarding.

General Notes

• The card scheme test systems (sandboxes) give no availability guarantees, and regularly undergo maintenance. That may result in temporary downtimes or HTTP error codes that indicate temporary server errors.
• The card scheme Test PANs are shared resources and in case of Visa permit only a limited number of tokenizations (see more details below).

Mastercard Test PANs - tested on 2025-02-04

Note

• Unlike documented on Mastercard's site test PANs are not always behaving in the same predictable way in the Sandbox environment.
• Therefore, the following list is providing some error scenarios as tested on 2025-02-04.
• It is NOT guaranteed, that those cards are always behaving in the same way.

Tokenization Eligible Test Cards

You can use any of the following test cards to simulate a successful card enrollment/tokenization scenario.

Card Number	Expiry Date	CVV
2222690420064590	Any Future Date	Any
2222690420064574	Any Future Date	Any
2222690420064582	Any Future Date	Any
5120350100064594	Any Future Date	Any

Tokenization Eligible Test Cards on Mastercard's site

Non-tokenizable Test Cards

You can use the following test cards to simulate the TOKENIZATION_INELIGIBLE scenario:

Card Number	Expiry Date	CVV
Currently, mastercard does not provide any cards to test TOKENIZATION_INELIGIBLE scenario

You can use the following test cards to simulate the PAN_INELIGIBlE scenario:

Card Number	Expiry Date	CVV
5460126128200800	Any Future Date	Any
5207980000000102	Any Future Date	Any

You can use the following test cards to simulate the INVALID_PAN scenario:

Card Number	Expiry Date	CVV
5204731601950473	Any Future Date	Any

Test Cards for Tokenization Declined by Issuer

You can use the following test cards to simulate a scenario where tokenization is declined by the issuer.

Card Number	Expiry Date	CVV
5120340000000392	Any Future Date	Any
5120350100000036	Any Future Date	Any

Visa Test PANs

NOTE: Due to the VTS tokenization rules, there is a maximum number of tokens (149) with which a Visa FPAN can be tokenized. This limit is valid for the VTS Sandbox as well as for VTS Production.

Therefore, when reaching that limit, the tokenization request will fail with following error: VTS_CARD_NOT_ALLOWED - tspMessage: The maximum number of tokens has been exceeded for the given PAN

Once the limit of maximum tokenizations is reached, the FPANs can’t be tokenized furthermore.

Related to testing, in order to avoid reaching this limit, you should use the same value for UserData -> accountId field in every request of the Tokenize API.

Please use unique values only to a very limited extent if you need to test token deletion functionality.

If you reach the error limit, you must use a new test PAN.

Eligible VISA Test PANs - tested on 2025-02-04

Card Number	Expiry Date	CVV
4622943123040843	2025-12	858
4622943123040850	2025-12	267
4622943123040868	2025-12	734
4622943123041601	2025-12	270
4622943123041619	2025-12	583
4622943123041627	2025-12	796
4622943123041635	2025-12	121

Any other PAN can be used for the non-eligible case.

Elo Test Data

Elo Test PANs

Tokenization Eligible Test Cards

As Elo currently does not allow tokenization of the same card twice, no permanently working test pans can be provided from eCOM side.

However, you can generate your own card PANs with the following test BIN range: 85051692

In order to generate a valid PAN, you must add a random 5-6 digit part to the test bin range, and add the valid checksum to the end. Therefore the maximum length of a valid PAN is 15 digits. You can generate pans according to the following schema: 85051692 + [0-9]{4, 6} + valid checksum digit

Elo Onboarding CNPJs

For ELO onboarding a CNPJ must be provided, as described in the onboarding section.

CNPJs for testing must also be created according to the rules of valid CNPJs. Otherwise, onboarding to ELO will fail.