> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```sh theme={"system"}
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`](/reference/vault-forwarding/add-vault-forward-authentication) API as follows.

<CodeGroup>
  ```json Request theme={"system"}
  {
      "kind": "mtls",
      "display_name": "mTLS",
      "fields": [
          {"key": "cert", "value": "{cert}"},
          {"key": "cert_key", "value": "{cert_key}"},
          {"key": "ca_cert", "value": "{ca_cert}"}
      ]
  }
  ```
</CodeGroup>

Note the created `id` of the authentication for later.

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

### 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`](/reference/vault-forwarding/add-vault-forward-authentication) API as follows.

<CodeGroup>
  ```json Request theme={"system"}
  {
      "kind": "mle",
      "display_name": "MLE",
      "fields": [
          {"key": "key_id", "value": "{key_id}"},
          {"key": "key", "value": "{key}"}
      ]
  }
  ```
</CodeGroup>

Note the created `id` of the authentication for later.

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

## 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme) 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`](/reference/vault-forwarding/make-vault-forward) as follows.

```json theme={"system"}
{
  "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.