Getting Started with Visa Developer

Visa Developer offers a set of Application Programming Interfaces (APIs) that gives you the ability to incorporate Visa functionality into your projects. This guide describes how to create an account, get credentials to start building your test project and connect to the sandbox for testing your project. Once you finish testing your project, you can request for moving it to the production environment. There's a variety of APIs that you can use to build your project.

Refer to Browse APIs to view a complete list of APIs available.

Create Account

Getting access to Visa Developer is as simple as registering your name, email address, organization and creating a password. After you authenticate your email address (which is delivered to your email inbox), you are ready to start developing your first project.

Click Register to create your account and get started with Visa Developer.

Once you log in to Visa Developer, you will see the dashboard. This dashboard is your login home page where you can create and manage your projects. A project within Visa Developer contains a set of APIs that you can access with one set of credentials. You do not need separate keys to access each API.

Create Project

Once you have the credentials, you are ready to create a project and then test connectivity.

Creating a project starts with selecting the APIs that you are going to use. Simply specify a project name and description, and then select the APIs you would like to use. Refer to Product Documentation for API reference information.

To create a project:

  1. Go to your dashboard.
  2. Click on Create New Project.
  3. Specify Project Name and Project Description (Note: This can be maximum 1000 characters).
  4. Select the APIs you are interested to use in your project.

Note: Depending on the APIs you select, you may need to submit a Certificate Signing Request (CSR). This is not required for all authentication methods.

  • Generate a CSR for me (default)

    During the creation of your project, you must be ready to save your certificate private key. This key is only available to download once. By continuing, you will be prompted to save your private key locally and your project will be registered. If you are using a Two-Way SSL authentication, refer to Configuring a Two-Way SSL Keystore Using an Auto-generated CSR section for more details.
  • Submit my own CSR

    If you are using a Two-Way SSL authentication, refer to Configuring Two-Way SSL Keystore Using Your Own CSR for more details on how to configure a Two-Way SSL Keystore with OpenSSL and your own CSR or how to configure a Two-Way SSL Keystore with Java Keytool and your own CSR.

Note: For some APIs, you may have additional Agreements (Terms and Conditions).

On your dashboard, you can find the following options:

  • Keys/APIs to access your API credentials.

    Note: Visa Developer allows you to easily generate the sample code for one of the endpoints for all the selected APIs. Before you can use your new project, you must save your certificate private key locally.

    Visa Developer generates the following types of certificates. Note: Depending on the APIs you select, you may need to submit a Certificate Signing Request (CSR). This is not required for all authentication methods.
    • Visa Developer Platform Certificate: This is a Server certificate and required for handshake (verification and validation) with Akamai. You must add this to your trust-store.
    • Geo-Trust Certificate: This is a third party issued certificate for secure connection to endpoint and required for Two-Way SSL.
    • Project Certificate: This certificate validates the project and provides permission to access the Visa Developer Resources (SBX/Cert/Prod). This has a validity period.
    • Visa Certificate for Callbacks (Two-Way SSL): This certificate type is basically required for Outbound services/APIs on Visa Developer. The service identifies this certificate as a requirement towards Two-Way SSL.
  • Configurations to configure the Outbound Callbacks, as applicable to the product that support this feature. Refer to Outbound Callback for more details.
  • Test Data to access the test data that has been generated for you based on the APIs you selected.
  • Project Settings to configure the system settings for the APIs (if applicable).
  • Sample Code to download the 'hello world' project that comes preconfigured with your API credentials.
  • Project Promotion to go through the steps to request a move from Sandbox to Production.

When Visa Developer launches new Products or APIs, you can easily add new Products or API(s) to your existing project in the Sandbox by simply editing your existing project. You can either add Products or APIs:

  • Product(s). For example: Visa Direct, Mobile Location Confirmation, etc.
  • API(s). For example: Funds Transfer API, Get Payment Data API, Locate ATMs API, Provision Token API, Merchant Locator API, Visa Travel Notification API etc.

To add new APIs to an existing project in the Sandbox:

  1. Go to your dashboard.
  2.  Select your existing Project from My Projects.
  3. Navigate to the Keys/APIs > APIs Included section.
  4. Click on Add APIs.

Note: For some APIs, you may have additional Agreements (Terms and Conditions).

Note: Currently Delete APIs is not supported. This means, once the project is created, you cannot unregister APIs from your project in the Sandbox.

In case you have already moved (or requested) your project from Sandbox to Production, you can request to re-promote your project with the newly added APIs. Please consider the following conditions:

  • There are newly added Products or APIs in the Sandbox
  • The previous project promotion request (if any) was completely processed by Visa and the project was promoted to Production

Visa Developer Sandbox is a fully functional environment that allows you to test publicly available API endpoints. To help you develop and test your project, the Sandbox provides you with all of the testing data. You can also refer to API Explorer to experience the API Endpoint and Request/Response parameters.

On your dashboard, click the project name to access the project details.

  • Copy/paste your project keys, test data and documentation for the API project.
  • Each API has an LED indicator:
    • Green indicates you can start to invoke the API.
    • Red indicates a failure and there will be no green after this. (There is no need to wait for the status anymore. You will need to create a new project.)
    • Gray indicates that you will have to wait for the status to turn green.

        If the LEDs show Activation in progress, click on the refresh icon next to the API to obtain the status.

Once you are ready to invoke your APIs in Sandbox, refer to the following URLs:

  • For all Business-to-Business (B2B) calls — send test requests to this URL: https://sandbox.api.visa.com/
  • For all Business-to-Consumer (B2C) calls — send test requests to this URL: https://sandbox.webapi.visa.com/
  • Note: Currently, Visa Developer only provides the Flex API/Token endpoint for B2C calls.

Authentication and Test Connectivity

In order to make your first API call, you must ensure that you have successfully establish the connection to the Sandbox environment. You will require credentials provided to you on the Visa Developer dashboard and configure the right authentication method for the API. 

Authentication Methods

The following table lists the supported authentication method for each product.

Product Name
Authentication Method
CyberSource Payments
API Key - Shared Secret (x-pay-token)
Digital Card and Account Services
Two-Way SSL (Mutual Authentication)
Foreign Exchange Rates 
Two-Way SSL (Mutual Authentication)
Fraud Inquiry
Two-Way SSL (Mutual Authentication)
Merchant Locator
Two-Way SSL (Mutual Authentication)
Merchant Measurement
Two-Way SSL (Mutual Authentication)
Merchant Search
Two-Way SSL (Mutual Authentication)
Mobile Location Confirmation
Two-Way SSL (Mutual Authentication)
Payment Account Attributes Inquiry
Two-Way SSL (Mutual Authentication)
Payment Account Validation
Two-Way SSL (Mutual Authentication)
Visa Checkout
API Key - Shared Secret (x-pay-token) for Visa Checkout
Visa Direct
Two-Way SSL (Mutual Authentication)
Visa Global ATM Locator
Two-Way SSL (Mutual Authentication)
Visa Merchant Offers Resource Center
Two-Way SSL (Mutual Authentication)
Preauhorized Payment Cancellation Service Two-Way SSL (Mutual Authentication)
Visa Offers Platform
Two-Way SSL (Mutual Authentication)
Visa Risk Manager
Two-Way SSL (Mutual Authentication)
Visa Token Service
API Key - Shared Secret (x-pay-token)
Visa Travel Notification Service
Two-Way SSL (Mutual Authentication)
Visa Consumer Transaction Controls Two-Way SSL (Mutual Authentication)
Visa Card Eligibility Service Two-Way SSL (Mutual Authentication)
B2B Virtual Account Payment Method Two-Way SSL (Mutual Authentication)
Visa B2B Connect Two-Way SSL (Mutual Authentication)
Visa Business Data Solutions Two-Way SSL (Mutual Authentication)
Visa Supplier Matching Service Two-Way SSL (Mutual Authentication)
Visa Account Updater Two-Way SSL (Mutual Authentication)
Visa Payments Processing Two-Way SSL (Mutual Authentication)
Issuer Measurement Two-Way SSL (Mutual Authentication)
Visa Chip Simulation Service Two-Way SSL (Mutual Authentication)
Visa Account Management Suite Two-Way SSL (Mutual Authentication)
Visa Queue Insights Two-Way SSL (Mutual Authentication)
Visa Threat intelligence Two-Way SSL (Mutual Authentication)

Visa Developer uses simple and effective authentication and authorization methods. Based on the APIs you select, use one of the following two standard and supported authentication methods for calling the APIs:

  • Two-Way SSL (Mutual Authentication)
  • API Key - Shared Secret (x-pay-token)

Refer to the Sample Code to see the sample code in various languages.

Two-Way SSL (Mutual Authentication)

As one of the security protocols, Visa Developer sandbox secures its connections with clients by means of Two-Way SSL (Mutual Authentication) method. 

Refer to the video below to quickly learn about how to get credentials to start building with Two-Way SSL.

In Two-Way SSL authentication, the client and server need to authenticate and validate each others identities. The authentication message exchange between client and server is called an SSL handshake, and it includes the following steps:

  1. A client requests access to a protected resource.
  2. The server presents its certificate to the client.
  3. The client verifies the server's certificate.
  4. If successful, the client sends its certificate to the server.
  5. The server verifies the client’s credentials.
  6. If successful, the server grants access to the protected resource requested by the client.

In step 5 (above), the server validates the client, which is the second part of the Two-Way SSL (Mutual Authentication) process. This is typically done by making sure that the client certificate is valid (non-expired and issued by a trusted Certificate Authority), as well as the client’s digital signature is valid. The digital signature is produced using the private key from the client. Anyone that has the public key can validate the digital signature. (However, only the client that has the private key can create a valid signature.)

To establish a Two-Way SSL (Mutual Authentication) connection, you must have the following:

  • private key
  • client certificate
  • certificate authority root certificate, and 
  • certificate authority intermediate certificates (Note: These certificates are optional for the Visa Developer sandbox)

The following sections explain how to obtain a private key, client certificate, and certificate authority root certificate. You will also learn about how to bundle the certificates into keystores, using Java keytool or OpenSSL.

In order to obtain a valid client certificate from Visa Developer, you must submit a Client Server Request (CSR). The CSR file contains client registration details (such as Organization Name and Locale), as well as the public key from the client. The process of creating the CSR yields the CSR file itself and also a private key (which corresponds to a public key, which is encoded into the CSR file). There are multiple tools that you can use to create a CSR, such as Java keytool or OpenSSL. Both tools are available for free to download from the Internet for all major operating systems.

Refer to one of the following sections on how to obtain a Two-Way SSL certificate.

  • Configuring a Two-Way SSL Keystore Using an Auto-generated CSR
  • Configuring Two-Way SSL Keystore Using Your Own CSR

Configuring a Two-Way SSL Keystore Using an Auto-generated CSR

Visa Developer creates the CSR file and submits the CSR to itself. The output of this process is the private key and the certificate of the client. 

Note: The auto generated CSR file is only available as an option in the Visa Developer sandbox when a project is created.

To auto-generate the CSR:

  1. On the dashboard, click on Create a New Project.
  2. Specify your Project Name and Project Description, then specify the APIs you are interested in using.
  3. Depending on the APIs you select, click on either Submit a Certificate Signing Request or Generate a CSR for Me.
    Visa Developer self-submits a certificate request and produces a .pem file with the private key of your certificate in it. This uses default values for Organization Name and Locale.
  4. Download the private key and store it in a secure location.
  5. In addition, you must download the ProjectCertificate and the Visa Developer Root Certificate (available in dashboard under Keys/APIs -> Certificates section).

Note: Once you complete the project creation process, Visa Developer Platform (VDP) will provide you with the links of the certificates to download. In this case, Visa Developer provides a VDP CSR. Once you obtain the private key and the certificates, you can begin to create the key stores and start testing mutual SSL connectivity.

The following steps include examples for context.

  1. Place your private key file (for example: privateKey.pem and your certificate file from VDP (for example: cert.pem in the same directory. Generate a keystore (for example: myProject_keyAndCertBundle.p12) file as shown below.
    > openssl pkcs12 -export -in cert.pem -inkey "privateKey.pem" -certfile cert.pem -out myProject_keyAndCertBundle.p12
    
    Note: The myProject_keyAndCertBundle.p12 is only a placeholder file name. You may choose to name it anything else.

  2. If you need a Java Key Store, run the following Java keytool command to convert your P12 file into a JKS file.
    > keytool -importkeystore -srckeystore myProject_keyAndCertBundle.p12 -srcstoretype PKCS12 -destkeystore myProject_keyAndCertBundle.jks
    
  3. Run the following Java keytool command to validate the contents of your new JKS file.
    > keytool -list -v -keystore myProject_keyAndCertBundle.jks
    
  4. Run the following command to add the root certificate to your JKS file.
    > keytool -import -alias ejbca -keystore myProject_keyAndCertBundle.jks -file VDPCA-SBX.pem -storepass <password>
    

Configuring Two-Way SSL Keystore Using Your Own CSR

Configuring Two-Way SSL Keystore with OpenSSL

OpenSSL is an open source software library that implements Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols, as well as provides basic cryptographic functions and various utilities.

Note: PCI DSS standard version 3.1 has been retired in October 2016 and the new PCI DSS version 3.2 mandates using TLS 1.2 (or higher) protocol and makes all older TLS versions (e.g. SSL v3, TLS 1.0, TLS 1.1) non-compliant. The standard requires the new TLS requirement to be implemented by June 2018. In preparation for this requirement, Visa plans to disable TLS 1.0 and TLS 1.1. These versions will be disabled first in Sandbox prior to Production to give you an opportunity to test these in Sandbox and ensure you are using TLS 1.2. For details, refer to the TLS Blog.

See below for a command-line utility, which is freely available for download from the Internet for all major operating systems.

  1. To generate a CSR and private key, run the command shown below from the command line. The command will prompt you for Country Name, State Name, Locality Name, Organization Name, Organization Unit Name, Common Name, and Email Address. For example, notice the output from the resulting files--one is the private key (privateKey.pem) and the other is the CSR (certreq.csr).

    > openssl req -new -keyout privateKey.pem -out   certreq.csr 
    Generating a 2048 bit RSA private key
    … 
    Writing a new private key to ‘privatekey.pem’ 
    Enter PEM pass phrase: <your_password> 
    Verifying – Enter PEM pass phrase: <re-enter your password> 
    You are about to be asked to enter information that will be incorporated into your certificate request. 
    What you are about to enter is what is called Distinguished Name or DN. 
    For some fields there will be a default value. 
    If you enter ‘.’, the field will be left blank 
    Country Name (2 letter code): <country name>
    State or Province Name (full name):<state name>  
    Locality Name (eg, city):<city name>
    Organization Name (eg, company):<organization name> 
    Organizational Unit Name (eg, section):<department/section name> 
    Common Name (eg, your name or your server`s  hostname):<host name>  
    Email Address []:<email address> 
    Please enter the following 'extra' attributes to be sent with your certificate request A challenge password:.
    An optional company name:
    

    Note: For all fields, only the following ACSII characters are allowed.

    • Space character
    • Upper case, A to Z
    • Lower case, a to z
    • Digits, 0 to 9
    • Dash (-)

    Country Name

    Two-digit International Standards Organization (ISO) 3166-1 country code. For example: US

    State Name

    Name of the state or province where the server is located. For example: California

    Locality Name

    A valid city name. For example: San Francisco

    Organization Name

    Name of your organization. For example: Bank of USA

    Organization Unit Name

    Name of the division within your organization. For example: Debit Card Processing Unit

    Common Name

    This field must contain a fully qualified domain name. Format should be alias/hostname.domainname.com. This must not contain any wildcard characters for the hostname. For example: services.visa.com

    CSR Unique Id (UID)

    Note: This is required for Certification or Production environment only

    The UID should be appended with one of the following values:

    • Certification environment: <UID>-CERT
    • Production environment: <UID>-PROD

    To get the CSR Unique Id, go to dashboard, select the Project Name for which you need to generate the CSR, and click on Settings.

  2. Upload your CSR file to Visa Developer.
    In response, Visa Developer will create your client certificate and the Visa Developer CA Root Certificate. Download both the Visa Developer Certificate (Root CA) and certificate (client cert) to a local folder.

    Note: You should see both VDPCA-SBX.pem and cert.pem in your local folder.
  3. Create the PKCS12 (P12) Certificate Store Using OpenSSL.
    In order to invoke Two-Way SSL with a majority of the non-java platforms, you will need the PKCS12 keystore, which is described below. Check your SSL library documentation, as some platforms accept the key and the certificate directly. If this is the case, you can skip this step.
    Note: The PKCS12 (P12) files can be imported into the Windows keystore using the Windows certificate import utility. This action will be invoked automatically when you double-click a P12 file.

Place your private key file (for example: privateKey.pem) and your certificate file from VDP (for example: cert.pemin the same directory.

Run the following OpenSSL command to create the P12 certificate store containing your private key and your client certificate.

  1. Generate a keystore (for example: myProject_keyAndCertBundle.p12) file as shown below.
    > openssl pkcs12 -export -in cert.pem -inkey "privateKey.pem" -certfile cert.pem -out myProject_keyAndCertBundle.p12
    
    Note: The myProject_keyAndCertBundle.p12  file is only a placeholder file name. You may choose to name it anything you choose.
  2. View and validate the contents of your P12 certificate store by executing the following OpenSSL command.
    > openssl pkcs12 -info -in myProject_keyAndCertChainBundle.p12
    

    The resulting file, called myProject_keyAndCertBundle.p12 will contain both your private key and your client certificate.

    Note: The Visa Developer sandbox does not validate the VDP root CA, so you do not have to include it in your P12 keystore. However, the root certificate is required when you create your Java Key Store, because you cannot add the client certificate to the JKS file without the root certificate. During the actual SSL handshake, the VDP sandbox does not validate the root certificate, so both JKS with the root cert and P12 without the root certificate will work equally well.

Configuring Two-Way SSL Keystore with Java Keytool

Keytool is a certificate management utility that is part of the standard Java distribution.

To generate a CSR using keytool:

  1. Generate a keystore file that contains public/private key pair (for example: 'clientkeystore.jks'), as shown below, using RSA, a keysize of 2048, and a password. Keytool manages everything through the Java Key Store (JKS).
    keytool -genkeypair -alias client -keyalg RSA -keysize 2048 -keystore clientkeystore.jks -storepass <password> -keypass <password> -dname "CN=<common name>, OU=<organizational unit>, O=<organization name>, L=<city/locality name>, ST=<state name>, C=<country name>"
    

    Note: For all fields, only following ACSII characters are allowed.

    • Space Character
    • Upper case A to Z
    • Lower case a to z
    • Digits 0 to 9
    • Dash (-)

    Country Name

    Two-digit International Standards Organization (ISO) 3166-1 country code. For example: US

    State Name

    Name of the state or province where the server is located. For example: California

    Locality Name

    A valid city name. For example: San Francisco

    Organization Name

    Name of your organization. For example: Bank of USA

    Organization Unit Name

    Name of your division within your organization. For example: Debit Card Processing Unit

    Common Name

    This field must be a fully qualified domain name. Format should be alias/hostname.domainname.com. This cannot have wildcard characters for hostname. For example: services.visa.com

  2. Generate the Certificate Signing Request (for example: 'certreq.csr') file from your Java Key Store as shown below. Be sure to copy the User ID and Password because you will need these to invoke APIs with Two-Way SSL.
    keytool -certreq -alias client -keystore clientkeystore.jks -storepass <password> -keypass <password> -file certreq.csr
    
    You now have the Java Key Store file (which contains your private key) and the CSR file.
    Certificate (root CA) and the certificate (client cert) to a local folder. You should see both VDPCA.pem and cert.pem in your local folder.
  3. Update Java Key Store with Root Certificate and Client Certificate using Java Keytool.

    To invoke an API using Two-Way SSL, you must have a client certificate and your root CA in your keystore, since your Java SSL library only accepts one input for all certificates – the keystore. Therefore, you will need to add the certificates downloaded from VDP to the keystore (for example: clientkeystore.jks) that you generated while creating the CSR.


To add a project-specific certificate to the keystore:

  1. Add the VDP CA Root Public Certificate to the keystore:
    keytool -import -alias ejbca -keystore clientkeystore.jks -file VDPCA-Sandbox.pem -storepass <password>
    
    Note: Replace the < password > above with the actual password that was used while creating the clientkeystore.jks.
    Click yes when prompted to trust the certificate option.

  2. Add the project specific certificate to the keystore:
    keytool -import -alias client -keystore clientkeystore.jks -file cert.pem -storepass <password>
    
    The resulting file, called clientkeystore.jks will contain your private key, your client certificate and your VDP CA root certificate.

Testing Two-Way SSL Connectivity Using SOAPUI

SOAPUI is a free and open source Web Service Functional Testing solution. With an easy-to-use graphical user interface, SOAPUI allows client developer's the ability to rapidly create and execute web service API functional tests. Visa recommends that client developers use SOAPUI or a similar connectivity tool to establish initial connection to the VDP sandbox.

Configuring SOAP UI Two-Way SSL Preferences

In order to configure Two-Way SSL, you must create the  Certificate Signing Request (CSR) and use Visa Developer to obtain the VDP root CA and project specific certificate. The certificates and the private key need to be bundled together into a keystore (either Java Key Store or PKCS12 keystore), as described in the Configuring 2-way SSL Keystore section.
Once the keystore file is available, follow these steps to configure SOAPUI Two-Way SSL preferences.

  1. Download SoapUI 5.4 from http://www.soapui.org
  2. Once installed, open SOAPUI and go to File > Preferences as shown below:
    soap_1
  3. Select the SSL Preferences tab, browse to your keystore file (either JKS or P12 file), and provide the keystore password. Make sure to check the requires client authentication checkbox below.
    soap_2

Creating a Helloworld REST Project

  1. Once in SOAPUI, click Project > New REST Project. Then, provide the following helloworld URI in the URI field:
    https://sandbox.api.visa.com/vdp/helloworld
    soap_3

Configuring the Helloworld API Request and Testing the Connection

  1. Fully expand the newly created REST project and double click Request 1 (this will automatically open when the project is created successfully). Select the Auth tab to add HTTP basic authorization. 
    soap_4
  2. Select authorization type as Basic and click OK.
    soap_5
  3. Provide Username and Password availability from VDP for your project. For the Pre-emptive Auth option select Authenticate pre-emptively.
    soap_6
  4. Click Submit Request (green chevron icon below) to test your connection. If successful, you should see the current timestamp in the response panel, as shown below.
    soap_7

API Key – Shared Secret (X-Pay-Token)

Some Visa Developer APIs require an API Key-Shared Secret Authenticationwhich 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.

Refer to the video below to quickly learn about how to get credentials to start building with x-pay-token.

Note: The x-pay-token used by Visa Checkout is slightly different than the x-pay-token described in this section. For more information, refer to API Key – Shared Secret (x-pay-token) for Visa Checkout.

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*

    Note: Refer to the section below on how to generate the x-pay-token value with SHA256 HMAC.

    Sample Header

    GET /vdp/helloworld?apikey=KSKDFJOP934ALSFDJP34 HTTP/1.0 
     Host: sandbox.api.visa.com
     Accept: application/json
     X-PAY-TOKEN: xv2:1455716783:f5d15ed23f825ac69cd42e6fa187a175ecf7e9566ce4f21e11bad49bed4cc363
    
  3. Request payload. Include any resource-specific request parameters in the request payload before you make a request.
  4. 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

    Note: For some products the context path is skipped while computing x-pay-token:
    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.
    Note: For some products the context path is skipped while computing x-pay-token.
    Product Part of the URL to be skipped while computing x-pay token Example
    Request URL Path to be used in x-pay-token calculation
    CyberSource /cybersource/ https://sandbox.api.visa.com/cybersource/payments/v1/authorizations payments/v1/authorizations
    Visa Checkout /wallet-services-web/ https://sandbox.api.visa.com/wallet-services-web/payment/data/{callId} payment/data/{callId}
    Visa Token Service   https://sandbox.api.visa.com/vts/provisionedTokens vts/provisionedTokens
    VDP Hello World /vdp/ https://sandbox.api.visa.com/vdp/helloworld helloworld
    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.
  2. Create the x-pay-token, as shown below:

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

Note: The shared_secret is the shared secret from the Project dashboard.

Constructing the HTTP Header

Depending on your system needs, Visa Developer APIs will allow you to setup one or more HTTP header variables as illustrated in the following table.

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. With an easy-to-use graphical user interface, SOAP UI allows you to rapidly create and execute web service API functional tests. It is highly recommended that you use SOAP UI, or a similar connectivity tool, to establish your initial connection to the Visa Developer sandbox.

Note: Prior to working with SOAPUI, you must Register and create a project that uses x-pay-token as an authentication service. Make sure that you have a valid API key and shared secret (available on Project dashboard).

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://sandbox.api.visa.com/vdp/helloworld?apikey=<value of your API key> (replace the value of API key query string parameter with the actual API key that you received from the Visa Developer Platform).

    SOAP_UI_Testing

  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.

    Generate Test Suite

  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.

    SOAP UI Groovy Script
  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.
    Run the script (by clicking the green chevron) and make sure that the value of x-pay-token is visible in the Log Output window.

    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)
    

    Groovy Code

  7. Double click Request 1 (the test step just above your new, for example: "groovy" script). Select Headers tab and click the green plus sign to add a new header.

    SOAP XPayToken

  8. Add a custom header for the x-pay-token. The value of this header is set dynamically, when you run the script.

    Note:
    You will need to use the following as the header value: ${#TestCase#xpayToken}.
    The header name will be static, and should be set to: x-pay-token. The resulting header setting will appear, as follows.

    SOAP XPayToken

  9. Run your test suite by first executing the script (by clicking the green chevron), and secondly by sending the test request (green chevron on the request page). If all is correct, you should see the current timestamp in the response.

  10. Run Groovy Script

Sample Code for Authentication Methods

Sample Code for Two-Way (Mutual) SSL

Copied to clipboard
import javax.net.ssl.SSLContext;
import org.apache.http.conn.ssl.SSLConnectionSocketFactory;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.ssl.SSLContexts;

// Load client certificate into key store
SSLContext sslcontext = SSLContexts.custom()
        .loadKeyMaterial(new File(KEY_STORE_PATH), KEY_STORE_PASSWORD.toCharArray(),
                PRIVATE_KEY_PASSWORD.toCharArray())
        .build();

// Allow TLSv1.2 protocol only
SSLConnectionSocketFactory sslSocketFactory = new SSLConnectionSocketFactory(sslcontext, new String[] { "TLSv1.2" }, null,
        SSLConnectionSocketFactory.getDefaultHostnameVerifier());

CloseableHttpClient httpClient = HttpClients.custom()
            .setSSLSocketFactory(sslSocketFactory).build();
                    

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

Copied to clipboard
import java.math.BigInteger;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.SignatureException;


public static String generateXpaytoken(String resourcePath, String queryString, String requestBody, String sharedSecret) throws SignatureException {  
    String timestamp = timeStamp();  
    String beforeHash = timestamp + resourcePath + queryString + requestBody;
    String hash = hmacSha256Digest(beforeHash, sharedSecret);  
    String token = "xv2:" + timestamp + ":" + hash;  
    return token;  
}  

private static String timeStamp() {  
        return String.valueOf(System.currentTimeMillis()/ 1000L);  
    }  

private static String hmacSha256Digest(String data, String sharedSecret)  
        throws SignatureException {  
    return getDigest("HmacSHA256", sharedSecret, data, true);  
}  

private static String getDigest(String algorithm, String sharedSecret, String data,  boolean toLower) throws SignatureException {  
    try {  
        Mac sha256HMAC = Mac.getInstance(algorithm);  
        SecretKeySpec secretKey = new SecretKeySpec(sharedSecret.getBytes(StandardCharsets.UTF_8), algorithm);  
        sha256HMAC.init(secretKey);  

        byte[] hashByte = sha256HMAC.doFinal(data.getBytes(StandardCharsets.UTF_8));  
        String hashString = toHex(hashByte);  

        return toLower ? hashString.toLowerCase() : hashString;
    } catch (Exception e) {  
        throw new SignatureException(e);  
    }  
}  

private static String toHex(byte[] bytes) {  
    BigInteger bi = new BigInteger(1, bytes);  
    return String.format("%0" + (bytes.length << 1) + "X", bi);  
}
                    

Sample Code For Project

Once you have successfully connected to the Sandbox, you can start working on your project.

Visa Developer provides a variety of sample to help you understand how Visa APIs work. The sample code demonstrates how to make an API call that uses either the x-pay-token or the Two-Way SSL authentication method. You can view sample code in 6 languages - PHP, Ruby, Node, Java, C# and Python.

You can get sample code for your first project from two sources:

  1. Sample Code under Project Dashboard
    Visa Developer generates the sample code for the Hello World project, which comes pre-configured with your API credentials. Once you have created your Project with the relevant APIs, you can go to Sample Code section under the Project dashboard. You can download the sample code by selecting the language from the section.
  2. Github
    Visa GitHub repository for sample code: Github Sample Code Page
    GitHub commit full SHA: dcc353da25fd3b723d5ea188f1f3c061a8533411

    You can also download the SampleCode- master.zip from: Download
    GitHub zip SHA 384: 7HiJ3M41AQRbyeUDdbvq+b8huL2NFT4GbuPCUNvCqABR3SxoOQao88gnnNetFtGc
    If you need an SHA 384 hash for an integrity check, you can use the following command:
    openssl dgst -sha384 -binary SampleCode-master.zip | openssl base64
    

You can use the Sandbox endpoints throughout your project development cycle, as well as for the project regression testing.

Note: Some APIs provide simulated payloads for error and exception scenarios, which are difficult to re-produce in the production environment. The simulated error and exception scenarios are provided to help you develop proper error handling, to ensure that you have good coverage of all provided test data, before connecting to the Visa certification or production environment.

Outbound Configuration

An outbound call is an HTTP callback. A project created with certain APIs on Visa Developer enables you to register the URLs on which you want to listen to the events. The callback triggers an HTTP POST to the configured URL when an event occurs. The client notified on the URL has the flexibility to take appropriate action on the notification. 

Note: The outbound configuration is supported only over Two-Way SSL (Mutual Authentication).

Sandbox Setup

Add Outbound Configuration

To setup an outbound callback:

  1. Login to your Visa Developer account.
  2. Click on Project and go to Configuration section on your dashboard.
  3. Click on Add Outbound Configuration. This displays a configuration entry dialog box.
  4. Enter details for domain, path (URL), for example, domain: https://testproject.herokuapp.comNote: The protocol must be HTTPS.
  5. Select the Product and Callback from the dropdown and click Submit.  A new callback configuration will be created in the product section.
  6. The callback configuration will be in “Pending” state until it is approved by Visa.
  7. Once approved, you will receive an approval mail and the configuration state will updated to “Approved” on Visa Developer. Your configuration is ready and live at this point.  Configuration related information can be seen via Details option.
  8. The setup requires configurations, which you need to perform as stated below:
    1. Download the Client Outbound Certificate (chain) from the Outbound Certificates section under Credentials tab of your Project on Visa Developer.  The chain file is a bundled certificate, containing client certificate, VICA intermediate and VICA root certificates.  
    2. Add this certificate chain in the trust store of your application hosted server. Note: Make sure your server certificate is issued via a certifying authority (CA) on the Visa trusted CA list. (Refer to Certificate Requirements section). Your server domain should be publicly available.
  9. Whitelist the Visa Outbound public IP: 198.241.162.104 at your end so that Visa notification requests are not blocked. Note: In an Outbound call, Visa acts as a client and you cannot submit a callback configuration for an event that you have already submitted and is in the pending approval state.

Once your outbound configuration is approved for a project, Visa Developer issues an HTTP POST request to the URL specified every time an associated event is triggered. The request's (outbound call) POST parameters will contain XML/JSON data relevant to the event that triggered the request.

Edit Outbound Configuration

You can edit the submitted configuration only after it has been approved by the Visa admin. Select the Details option available for your outbound configuration and select an Edit option (pencil icon), which will allow you to edit the Domain and Path. After you modify the Domain parameter, Visa will be notified of it and will review the request for approval. The configuration in the interim will be in “Pending” state. Post Visa approval, the configuration state is updated to “Approved” at which point the configuration is live.

Note: If you only change the Path parameter, it will not require a re-approval from Visa.

Reject Outbound Configuration

Visa may reject your submitted outbound configuration if there is an issue in verification. If rejected, you will see the configuration in “Rejected” state on Visa Developer and rejection comments will be available under Details.

Outbound Configuration Setup Requirements

Two-Way SSL (Mutual Authentication) requires certificate exchange for the client and server to identify themselves and establish a tunnel. Refer to the Mutual Authentication blog for more details.

For Sandbox:

  1. Configure your application hosted server by adding the Visa issued client certificate chain into the trust store. This certificate chain is provided by Visa in the Outbound Certificates section under Credentials tab of your project on Visa Developer. You can download the chain using the Download Certificate option. This certificate chain is a bundled certificate, containing client certificate, VICA Intermediate and VICA Root certificates.
  2. For trusting your server side certificate, it should be issued by a known and Visa trusted Certificate Authority (CA). Self-signed certificates are not accepted. For a detailed list of trusted certifying authorities, click here.

Test Outbound Configuration

Visa Developer allows you to test your outbound configuration and verify that the URL is reachable by sending a test payload.

  1. Click Ping Test , which will display the test modal.
  2. Select the Product, Callback and the Callback Event. The request shows a sample payload structure as a reference only. The actual payload you receive will have different values as per your project configuration.

Click on Test Outbound, which will send a payload to your application hosted at the URL specified, and your application response will be displayed on the test modal. Response would be either 200 Ok or 5xx error from your application.

Certification and Production Setup

Add Outbound Configuration

You can submit outbound API configurations in certification and production from Visa Developer via Project promotion request or from Configuration section of the project once it is promoted to certification or production environment.

Via Project Promotion

1.       Your project promotion request form (for certification or production) will have your outbound APIs also promoted to higher environment

2.       You can enter the configuration details (domain and path) in the promotion form for each of the outbound APIs and submit the form.

Note: The outbound configuration submission from promotion request will be optional

3.       Post submission Visa will review your promotion request.

4.       If the request is reviewed and approved by Visa and an applicable VDP API Agreement is in place, your project will be promoted to certification or production (as requested) and you will be notified of the same by mail.

5.       You will receive acknowledgement mail for your submitted outbound configurations and Visa will verify those for approval.

6.       You can login to your Visa Developer account and go to your project Configuration section, where you will notice the outbound configuration(s) in "Pending" state.

Via Project Configuration Section

You can also submit outbound API configurations for your project from from Configuration section.

Note: For certification and production environment, your project promotion request should be Visa approved before you can access Configuration section.

1.        Login to your Visa Developer account.

2.       Click on the Project and go to Configuration section on your project (certification or production to which your project is promoted)

3.       Click on Add Outbound Configuration. This displays a configuration submission modal.

4.       Select the outbound API, enter configuration details: domain, path and click Submit. For example, domain: https://testproject.herokuapp.com

Note: The protocol must be HTTPS.

5.       A new outbound configuration will be added for the API and you will get an acknowledgement mail.

6.       The configuration will be in “Pending” state and Visa will verify the configuration details before approving.

 

Verify and Activate Outbound Configuration

1.       Visa will review your submitted configuration, and once reviewed the configuration may be approved.

2.       An approval will trigger provisioning of your public client certificate (Visa Information Delivery Certifying Authority signed).

Note: The SLA for provisioning the client certificate is 3 to 4 days.

3.       Once the client certificate is provisioned, the configuration status will change to "Approved" and the configuration state will be “Inactive”.

4.       The certificate provisioning will provide the public certificate, VICA intermediate and VICA root certificates for you to download from Visa Developer dashboard (Go to Outbound Certificates section under Project Credentials).

5.       Visa will notify you (via email) of the client certificate provisioning and as a next step, you will be required to configure your server. Refer to steps below or read Outbound Configuration Setup Pre-requisites for more details.

         i.     You can download all 3 certificates from the Visa Developer dashboard, and create a certificate chain (.pem file). For details, refer to Certificate Chaining Steps.

         ii.    Once the certificate is chained and you have the .pem file, add it to your trust-store (required for Mutual-SSL handshake).

         iii.   Next, make sure you have whitelisted public IPs for Visa: 198.241.162.104 & 198.241.168.15.

6.       After you are done with your server setup, you can activate the callback using the activation Toggle. This will trigger the activation, which will take a few minutes. The callback status in the interim will be "Activation_Pending".

7.       Post the activation is successful, the callback status changes to "Active" and you will be notified (via email) of configuration completion and activation.

8.       You can now proceed for testing configuration via Ping Test option available.

De-activate Outbound Configuration

You can de-activate an active outbound configuration anytime from the Developer Portal.

1.       Login to developer portal and go to Project configuration under Certification or Production section.

2.       Disable the callback using Toggle option, which when exercised will change the state of callback to "De-activation_Pending".

3.       Post de-activation is successful, the configuration state will change to "Inactive".

4.       You may choose to activate the configuration again, as and when required using the Toggle option.

Note: The outbound configuration status remains “Approved” and only state changes to “Active”/”Inactive” via the toggle.

Test Outbound Configuration

1.       As your outbound configuration is activated and the state reflects as "Active" you can proceed to test the same using Ping Test.

2.       Click on Ping Test option for the callback and a modal will be displayed listing the Product, Outbound API and API end-point.

3.       The Request section on the modal will show a sample payload structure as reference. This payload provides information to client on what attributes and values he would receive in the outbound request.

Note: The sample payload is non-editable.

4.       Click on Send Test and you will receive a payload on your hosted end-point.

5.       The response from your end-point will display on the modal under Response section. A 200Ok response means the configuration is successful and the connectivity is established.

Note: Make sure you have your end-point setup and server configured correctly. For details, refer to Callback Setup Pre-requisites section.

 

Edit Outbound Configuration

1.       Login to your Project on Visa Developer dashboard and go to project Configuration section.

2.       Click on Details option for the configuration you want to edit.

3.       Select the Edit option (pencil icon) from the top of the Edit modal.

Note: You cannot edit a configuration that is in "Pending" state. 

3.       The configuration domain and path fields will become editable on the modal, which you can modify and submit.

4.       A new configuration (endpoint) will be created on the portal and it will be in "Pending" state.

Note: Your existing (old) configuration URL will remain “Active” and you will continue to receive outbound calls on it, until the new one is approved.

5.       Visa will acknowledge receipt of your edited configuration and will verify the same.

6.       Post verification, Visa will approve the configuration and old configuration will replace by new (edited) configuration.

Note: While the edited configuration is under review and approval, please make sure you have both the old and new URLs hosted.

8.       Once the new configuration is updated it will be updated to “Approved” status and state will be "Active". Your old configuration will cease to exist at this point.

You can now proceed for testing the new configuration via Ping Test option.

Delete Outbound Configuration

Deletion of an outbound configuration is not supported in certification and production environment.

Re-submit Rejected Outbound Configuration

1.       Visa has the right to reject an outbound configuration submitted by you if it finds that domain is not valid or it is not owned by you.

2.       Visa will provide rejection comments which will be visible to you on the Developer portal in “comments” field under “Details” modal.

3.       The configuration status will be "Rejected" on Visa Developer.

4.       You can correct the callback URL (domain/path) using the "Edit" option and re-submit the configuration.

5.       The configuration will again undergo review by Visa.

Outbound Configuration Setup Pre-requisites

For the configuration setup to work you are required to perform the below:

1.       Your server certificate needs to be provisioned by one of the Visa trusted CA (Certifying Authority) only.

For a detailed list of Visa trusted certifying authorities, click here

2.       You need to whitelist Visa public IP(s): 198.241.162.104 & 198.241.168.15

3.       You need to configure the client outbound certificate chain (public certificate, VICA intermediate and VICA Root) in your server trust-store. All these certificates will be available for your project from Visa Developer dashboard. Make sure you download the right certificate for the correct environment (certification or production)

Certificate Chaining Steps

1.       Make sure you have download the outbound certificates for your project from Visa Developer dashboard.

2.       Open a text editor (notepad/wordpad) and paste the entire body of each certificate into one text file in the following order:

  • The Primary Certificate - <<projectName>>_client_certificate.crt
  • The Intermediate Certificate - VICAIntermediateCA.crt
  • The Root Certificate - VICATrustedRoot.crt
  • Make sure to include the beginning and end tags on each certificate. The result should look as shown  below:

-----BEGIN CERTIFICATE-----
<<Your client certificate: client_outbound_certificate.cert>>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<<Your Intermediate certificate: VICAIntermediateCA.cert>>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<<Your Root certificate: VICATrustedRoot.cert>>
-----END CERTIFICATE-----

3.       Save the above file as your_project_domain_name.pem. You can now configure the certificate chain (.pem file) in trust store of your server. 

Promote Project

Visa Developer now has a new worflow to promote project from sandbox to certificate or production environment. For details, please refer to Going Live with Visa Developer Project.