Visa Developer Community

Highlighted
Visa Employee

VTS X-Pay-Token Troubleshooting Guide

VTS X-Pay Token Troubleshooting Guide - Common Errors and Possible Resolutions 

 

Written by Shruti Tandon and @Jitesh_Shah 

 

Please find below the common errors/issues faced by developers while using X-Pay-Token in Visa Token Service (VTS) Use Cases. These steps will help in checking/making sure the X-Pay-Token is being Generated and Used in a correct manner.

 

#1 Error Scenario Details 

 

 

{
    "responseStatus": {
        "status": 401,
        "code": "9201",
        "severity": "ERROR",
        "message": "Token Validation Failed",
        "info": ""
    }
}

 

 

 

Possible Resolutions :

  1. APIKEY used must be environment specific. Production API Key and shared secret must not be used to generate x pay token in Sandbox environment.
  2. API Key and Shared Secret used for creation of X Pay Token must be of type “Inbound” or “Default”.
  3. The API Key/Shared Secret used for X Pay Token Generation must be present under Credentials tab in VDP.  

 

# 2 Error Scenario Details 

 

 

 

{
    "responseStatus": {
        "status": 401,
        "code": "9159",
        "severity": "ERROR",
        "message": "Token Validation Failed",
        "info": ""
    }
}

 

 

Possible Resolutions:

 

a. The resource path used in the generation of x pay token must not have “/” in the end. Please find below examples related to resource path.

 

Example :

  • API - Get Token status request
  • Sandbox Path- https://cert.api.visa.com/vts/provisionedTokens/ {vProvisionedTokenID}?apiKey=key
  • Correct Resource Path - vts/provisionedTokens/{vProvisionedTokenID}
  • Incorrect Resource Path - vts/provisionedTokens/{vProvisionedTokenID}/

 

bThe word “apiKey” used in queryString while generating x-pay-token is case sensitive and must be same as what is passed in request.

 

Example :

 

c. “?” must not be part of query string or resource path while generating x pay token

 

Example :

 

  • Correct QueryString- apikey={key}&async=false
  • Incorrect QueryString- ?apikey={key}&async=false

 

  • Correct Resource Path- /vts/provisionedTokens/{vProvisionedTokenID}
  • Incorrect Resource Path- vts/provisionedTokens/{vProvisionedTokenID}?

 

  • Sample before hash: {timestamp}vts/provisionedTokens/{vProvisionedTokenID}apikey={key}

 

d. There must not be any space “ “, new line "\n" or “.” in the request payload or at the end as compared to the one used in creating the x-pay-token.

 

Example:

  • Payload used in Enroll Pan Request

 

{"clientAppID":"appid1234","consumerEntryMode":"KEYENTERED","encPaymentInstrument":"eyJhbGciOiJBMjU2R0NNS1ciLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiUUhGTzAzSEhWMTNRN01LTTFYVzYxM2VIbEw3NndROVNtRy13R3VwWDNmaEQ3dkJaVSIsIml2IjoiUEVZSkQ5VVFfLTNOYzFieSIsInRhZyI6InRYSE5Ed2xla2ZZaGo2cDJ2S1dLbFEifQ.CaKqGn6vmgv8W6rZwSg9Gaz0IU8xI1jDlUsqAZogeKo.gMIF1v5eH8k82Tl1mks2Lh_FxOJepKD8DgDKjChG_-U.hTBNvI1yuzTQQSVg64WZnBwshbUdEAiS9AuMqWoUx5smhBOiBE2o8onz71iykkV_ZOXmM7BtJMxazgQtMueimcYUCM8KyxAjYQiyPGwfp80EcPH_eEG0O_TJueVRAV06KfxEMFvq02X4qHFD08me_54XLKnKd1MxN847gDzNrliLt0mlEFloWRKfBHBkJLBb_GDopdrScV0WvIF7hWXqmtNrhwqoOEBQHtEwtt4OJZgPeWcEnn_5dOgVBqZ__Vd1fL2QNOLWXPyT09Wgr9Bgj9fHWVmdSFmRbTvSctYxN_pf_QL2vr18VAPPsuraXeQ.iLw1SuzRLKhxjaBahPFv1A","locale" :"en_US","panSource":"MANUALLYENTERED"}

 

 

  •  Pay load used while creating X pay Token

 

 

"{\"clientAppID\":\"appid1234\",\"consumerEntryMode\":\"KEYENTERED\",\"encPaymentInstrument\":\"eyJhbGciOiJBMjU2R0NNS1ciLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiUUhGTzAzSEhWMTNRN01LTTFYVzYxM2VIbEw3NndROVNtRy13R3VwWDNmaEQ3dkJaVSIsIml2IjoiUEVZSkQ5VVFfLTNOYzFieSIsInRhZyI6InRYSE5Ed2xla2ZZaGo2cDJ2S1dLbFEifQ.CaKqGn6vmgv8W6rZwSg9Gaz0IU8xI1jDlUsqAZogeKo.gMIF1v5eH8k82Tl1mks2Lh_FxOJepKD8DgDKjChG_-U.hTBNvI1yuzTQQSVg64WZnBwshbUdEAiS9AuMqWoUx5smhBOiBE2o8onz71iykkV_ZOXmM7BtJMxazgQtMueimcYUCM8KyxAjYQiyPGwfp80EcPH_eEG0O_TJueVRAV06KfxEMFvq02X4qHFD08me_54XLKnKd1MxN847gDzNrliLt0mlEFloWRKfBHBkJLBb_GDopdrScV0WvIF7hWXqmtNrhwqoOEBQHtEwtt4OJZgPeWcEnn_5dOgVBqZ__Vd1fL2QNOLWXPyT09Wgr9Bgj9fHWVmdSFmRbTvSctYxN_pf_QL2vr18VAPPsuraXeQ.iLw1SuzRLKhxjaBahPFv1A\",\"locale\":\"en_US\",\"panSource\":\"MANUALLYENTERED\"}"

 

 

#3 Error Scenario Details

 

 

{
    "responseStatus": {
        "status": 401,
        "code": "9102",
        "severity": "ERROR",
        "message": "Token Validation Failed",
        "info": ""
    }
}

 

 

 

Possible Resolutions:

 

  1. Timestamp is the current timestamp in UTC (in seconds) and must not be hardcoded. Timestamp in x pay token (last step) and used while generating x pay token must be same. 

--Pseudo code

 

 

beforeHash = timeInSeconds + resourcePath + queryString;
create hash using HmacSHA256(beforeHash) with secretKey
xPayToken ="xv2:" + timeInSeconds + ":" + hash;

 

 

 

b.  X-pay-token used in the request must not be reused or expired. The expiration period is set to 480 seconds.

 

#4 Error Scenario Details

 

 

{
    "errorResponse": {
        "status": 401,
        "message": "Token Validation Failed",
        "reason": "inputValidationError",
        "details": [
            {
                "message": "Token validation failed since expected tokenValue for x-pay-token was not present",
                "location": "x-pay-token"
            },
            {
                "message": "Token validation failed since expected tokenValue for authorization was not present",
                "location": "authorization"
            }
        ]
    }
}

 

 

 

Possible Resolution:

 

a. X pay token must be passed as part of header parameters. The header parameter name must be x-pay-token (case insensitive)

 

#5 Error Scenario Details

 

 

{
    "responseStatus": {
        "status": 401,
        "code": "9101",
        "severity": "ERROR",
        "message": "Token Validation Failed",
        "info": ""
    }
}

 

 

 

Possible Resolution:

 

a. X pay token must be created in below format:

 

"xv2:" + timestamp + ":" + HMAC-SHA-256((shared -secret +) (timestamp + Resource path + query string + entity body).

 

2 REPLIES 2
Highlighted
Visa Employee

VTS X-Pay-Token Troubleshooting Guide

Hope this helps - please let us know if you run into any issues and you need our help!

 

 

Highlighted
Visa Dev Moderator

Re: VTS X-Pay-Token Troubleshooting Guide

Hey @Jitesh_Shah,

 

Thanks for sharing this with us, it's really helpful.

 



Was your question answered? Don't forget to click on "Accept as Solution" to help other devs find the answer to the same question.

Thanks,
Diana