Advanced authentication for Visa

Prerequisites

Please ensure the Visa endpoints have been enabled for your instance by the support team.

Setup

Once the Visa endpoint has been enabled, head over to the dashboard, switch to Settings -> Manage merchants then edit your merchant account using the actions menu, and then Edit merchant. In a single merchant environment you may be able to go to this screen directly via the Settings -> Configuration menu. Next, switch to the Vault Forwarding tab and you should see the Visa endpoint enabled for your environment. In the actions menu an option to edit the Authentication methods should be available. Select this menu, and it takes you to a new screen to set up an authentication. Visa has 2 authentication methods that can be set up: message level encryption (MLE) and mutual TLS (mTLS).

Mutual TLS (mTLS)

Mutual TLS ensures that all data between the system and Visa is encrypted at the TLS (SSL) level. This is generally a required authentication method for Visa endpoints and is the same for any merchant account. To set up mTLS, head over to the Visa Developer Center and switch to your merchant account, Credentials, and register a new certificate. Once set up, a private key and 2 certificates should be available. You can always redownload your certificate from the Visa dashboard by going to Credentials -> Actions -> Download Certificate. Similarly, you can download the DigiCert Global Root CA’ certificate from the Visa dashboard as well. This root certificate may require conversion to the pem format.

openssl x509 -inform der -in Downloads/DigiCertGlobalRootCA.crt -outform pem -out DigiCertGlobalRootCA.pem

You can now upload this certificate (cert), private key (cert_key) and root certificate (ca_cert) via the dashboard by selecting the Mutual TLS authentication method. Alternatively, you can use the POST /vault-forward/configs/{instance_id}/authentications API as follows.

{
    "kind": "mtls",
    "display_name": "mTLS",
    "fields": [
        {"key": "cert", "value": "{cert}"},
        {"key": "cert_key", "value": "{cert_key}"},
        {"key": "ca_cert", "value": "{ca_cert}"}
    ]
}

Note the created id of the authentication for later.

Please ensure keys and certificates are uploaded in a multiline format, without any extra spaces, new lines, or other characters.

Message Level Encryption (MLE)

Message Level Encryption encrypts the payload sent to Visa, and this is generally recommended for most Visa endpoints that send sensitive PCI data. This can be configured on a per merchant basis. To set up MLE, create a new key via the Visa Developer Center -> Merchant name -> Credentials -> Encryption/Decryption. Note the key ID and key value. You can then send this key (key) and key ID (key_id) via the dashboard by selecting the Message Level Encryption authentication method. Alternatively, you can use the POST /vault-forward/configs/{instance_id}/authentications API as follows.

{
    "kind": "mle",
    "display_name": "MLE",
    "fields": [
        {"key": "key_id", "value": "{key_id}"},
        {"key": "key", "value": "{key}"}
    ]
}

Note the created id of the authentication for later.

Please ensure keys are uploaded in a multiline format, without any extra spaces, new lines, or other characters.

Usage

To connect to the Visa API, create an HTTP request with the following headers.

x-vault-forward-url: https://sandbox.api.visa.com/vop/v1/users/addcard or the production equivalent
x-vault-forward-http-method: POST
x-vault-forward-payment-methods: the ID’s for each of the payment methods to forward
x-vault-forward-header-content-type: application/json
x-vault-forward-header-authorization:
- Go to Visa Developer Center -> Merchant name -> Credentials -> expand row
- Generate basic authentication header with the given User ID and Password.
x-vault-forward-authentications: the comma separated IDs of the mTLS and MLE authentication methods set up earlier

Then, make a POST request to /vault-forward as follows.

{
  "card": {
    "expirationYear": "{{ CARD_EXPIRATION_DATE_YYYY_1 }}",
    "cvv": "123",
    "nameOnCard": "Test ABC",
    "billingZipCode": "94354",
    "expirationMonth": "{{ CARD_EXPIRATION_DATE_M_1 }}",
    "cardNumber": "{{ CARD_NUMBER_1 }}"
  },
  "userKey": "9890124569",
  "communityCode": "GAP"
}

Mutual TLS and merchant level encryption are automatically applied to the API request sent to Visa. The payload and headers received from Visa are returned like any other forward request. It’s expected that the output is encrypted as merchants are expected to decrypt the response data themselves.

Get started

Integration guides

Best Practices

Resources

Features

Other

Advanced authentication for Visa

Prerequisites

Setup

Mutual TLS (mTLS)

Message Level Encryption (MLE)

Usage

​Prerequisites

​Setup

​Mutual TLS (mTLS)

​Message Level Encryption (MLE)

​Usage

Prerequisites

Setup

Mutual TLS (mTLS)

Message Level Encryption (MLE)

Usage