Advanced authentication for Visa

​

Prerequisites

Please ensure the Visa endpoints have been enabled for your instance by our 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, … -> 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 should have an option to edit the Authentication methods. Click on this menu, and it will take 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 our system and Visa is encrypted at the TLS (SSL) level. This is generally a required authentication method for Visa endpoints and will be 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 you should have a private key and 2 certificates. 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/{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.

​

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/{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.

​

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"
}

We will automatically apply mutual TLS and merchant level encryption to the API request sent to Visa.

We will return the payload and headers received from Visa like any other forward request. It’s expected that the output is encrypted as merchants are expected to decrypt the response data themselves.