Visa Developer | X-Pay Token

API Key – Shared Secret (X-Pay Token)

Some Visa Developer APIs require an API Key-Shared Secret Authentication, which Visa refers to as X-Pay Token. To invoke an API using X-Pay Token, you will need an API Key and a Shared Secret, which is provided on the project details page.

Get your API Key and Shared Secret

Select the environment in the left side navigation and expand the "Credentials" to locate "X-Pay Token."

The API Key and Shared Secret can be found under the "X-Pay Token" section under the Credentials tab of your dashboard.

Set up Shared Secret Encryption

1. Generate Public and Private Key Pair

2. Format Public Key

3. Upload to Visa Developer Center to encrypt Shared Secret

4. Decrypting Shared Secret with Private Key

Generating the X-Pay Token

To successfully invoke your Visa Developer APIs, which use X-Pay Token, your project must include the following:

  1. Add the API Key as the query parameter.
  2. Include the Accept and X-Pay Token in the request header as shown in the sample below.
Field Value
Accept application/json
X-PAY-TOKEN x-pay-token*

Sample Header

GET /vdp/helloworld?apikey=KSKDFJOP934ALSFDJP34 HTTP/1.0
Host: cert.api.visa.com
Accept: application/json
X-PAY-TOKEN: xv2:1455716783:f5d15ed23f825ac69cd42e6fa187a175ecf7e9566ce4f21e11bad49bed4cc363
  1. Request payload. Include any resource-specific request parameters in the request payload before you make a request.
  2. Test different scenarios using the test data provided on the Project dashboard.

Generating the X-Pay Token

To generate the X-Pay Token, follow these steps:

  1. Generate a message string by concatenating the following parameters:

message = timestamp + resource_path + query_string + request_body
Parameters Description
timestamp This is the current timestamp in UTC (in seconds).
resource_path This is the API endpoint you would like to invoke after the context path.
query_string The apikey is a required query parameter. Query parameters should be in lexicographical order.
request_body This is the API endpoint-specific request body string.
  1. Create the X-Pay Token:

XPayToken = "xv2:" + timestamp + ":" + SHA256HMAC(shared_secret, message)

Constructing the HTTP Header

Variable Name Value
Content-Type Optional
Specify request format
- XML Use text/xml
- JSON Use application/json
If not specified, expects JSON.
Accept Optional
Specify request format
- XML Use text/xml
- JSON Use application/json
If not specified, defaults to request format.

Testing X-Pay Token Connectivity Using SOAPUI

SOAPUI is a free and open source Web Service Functional Testing solution. It is highly recommended that you use SOAP UI, or a similar connectivity tool, to establish your initial connection to the Visa Developer sandbox.

SOAPUI REST project

  1. Download SoapUI 5.4 from https://www.soapui.org.
  2. Once installed, open SOAPUI and select File > New REST Project. Use the following URI: https://cert.api.visa.com/vdp/helloworld?apikey=.
  3. Once the project is created, in project navigator, right click the URI, and select Generate TestSuite. Specify name for your test suite and click OK.
  4. In the project navigator, fully expand the newly created test suite and locate the test steps.
  5. Right click Test Steps, select Add Step, then select Groovy Script as shown below. Specify name for your script and click OK.
  6. Paste the following contents into the script body. Make sure to replace the API key and the shared secret with your own values from the Visa Developer Center.
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

def hmac(String secretKey, String data) {
    Mac mac = Mac.getInstance("HmacSHA256")
    SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256")
    mac.init(secretKeySpec)
    byte[] digest = mac.doFinal(data.getBytes())
    return digest
}

def APIKey = 'VALUE_OF_YOUR_API_KEY'

def sharedSecret = 'VALUE_OF_YOUR_SHARED_SECRET'

def URI = "helloworld"

def QS = "apikey="+APIKey

def timeStampUTC = String.valueOf(System.currentTimeMillis().intdiv(1000L))

def payload = ""

def HMACDigest = hmac(sharedSecret, timeStampUTC + URI + QS + payload)

def encodedDigest = HMACDigest.encodeHex().toString()

def XPayToken = "xv2:" + timeStampUTC + ":" + encodedDigest

testRunner.testCase.setPropertyValue("xpayToken", XPayToken)
log.info(XPayToken)
  1. Double click Request 1. Select Headers tab and click the green plus sign to add a new header. The header name will be static and should be set to: x-pay-token.
  2. Run your test suite by first executing the script and secondly by sending the test request. If all is correct, you should see the current timestamp in the response.

Sample Code for API Key – Shared Secret (X-Pay Token)