Alias Directory offers the capability to connect to remote directories via a component called Directory Network Manager. Directory Network Manager has the capability to query available remote directories with an Alias and retrieve the associated payment details, if available.
The steps apply for both sandbox and production environments.
Client
Fill out onboarding form
Client
Code to API specifications
Client and Visa
Exchange OAuth credentials
Client and VIsa
Exchange IP Addresses for whitelisting
Client and Visa
Exchange MLE keys
Client
Provide SSL certificate chain
Client
Complete test cases
Step |
Description |
Details |
|---|---|---|
1 |
Remote Directory Onboarding Form |
Implementation manager to provide Directory Network Manager onboarding form. The form contains the Remote Directory Profile and OAuth 2.0 Setup Details. Remote Directory to fill out and send back to implementation manager. |
2 |
API Specifications |
Remote Directory to expose API endpoints according to Directory Network Manager API specifications here: The URI should follow the below format:
<https://<server-name>/<base-uri-defined-by-the-client>/aliases/resolve>
|
3 |
OAuth Credentials |
Remote Directory to provide OAuth credentials securely to implementation manager. This can be done in parallel with the API development. |
4 |
Whitelist IP Addresses |
Implementation manager will provide IP addresses to Remote Directory for whitelisting. Note: Directory Network Manager does not need Remote Directory IPs for whitelisting. |
5 |
MLE Setup |
Remote Directory and Visa implementation manager to exchange MLE credentials. The Remote Directory will submit a CSR request to the implementation manager. This CSR will be signed by Visa. The Remote Directory should save the private key used to generate the CSR. Implementation Manager will share the “Visa Online CSR” form to Remote Directory. Remote Directory will fill the “Visa Online CSR” form and return it to Implementation Manager. This form is the input to create the public certificate of Directory Network Manager. Implementation manager will share the public certificate of Directory Network Manager. |
6 |
SSL |
The Remote Directory will need to provide the certificate chain to the implementation manager. |
7 |
Test Cases |
The Remote Directory must complete the test cases provided by the implementation manager. |
| 8 | Remote Directory Service Level Requirements |
|
If a remote directory would like to connect to Directory Network Manager, the below information will need to be provided as part of onboarding.
| Key Terms | Definitions |
|---|---|
Remote Directory Name |
The name of the directory. This parameter will also be used in API calls when clients want to ping a specific directory. |
APIs Exposed |
This indicates the APIs that the Remote Directory will expose to Directory Network Manager. Valid values:
|
Supported Country Codes |
Specifies the country codes of the requestor that are allowed by the remote directory. For example, if the remote directory only supports “USA”, but the requestor is in “PERU”, then this directory won’t be called in the resolution process. |
Supported Alias Types
|
Valid values:
|
Remote Directory Base URL |
The base URL of the Remote Directory exposed endpoints. |
List of Entity Ids |
The entity Id is used by some remote directories to identify the entities within their directory. For example, a remote directory may have multiple banks within its directory. The Alias Resolution request can be sent to a specific bank within that remote directory by using that bank’s entity ID. |
The Remote Directory should provide the below OAuth information in the Remote Directory onboarding form.
| Information |
Description |
|---|---|
Client ID |
The client_id is a public identifier for apps. |
Client Secret |
The client_secret is a secret known only to the application and the authorization server Note: This must be shared in a secured communication with Visa. |
Authentication Path
|
Path of the authentication API which Directory Network Manager can use to get a JWT (Access token). |
OAuth 2.0 Grant Type client_credentials must to be used for API authentication between the Directory Network Manager and the remote directory. During the Remote Directory setup, Visa will receive a set of credentials to consume an authentication API that the Remote Directory will expose, specifically:
Client ID and Client Secret:
https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/
The path of authentication API which Directory Network Manager can use to get a JWT (Access token) should also be provided to Visa. The JWT must be created according the following specifications for the request and response:
Client Credentials:
Please note that the grant_type parameter must be set to client_credentials.
https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/
Access Token Response:
https://www.oauth.com/oauth2-servers/access-tokens/acc process the response.
During test, client should expect a call from Directory Network Manager with the following format. Please note that the content type to be used is “Content-Type: application/x-www-form-urlencoded”
Start a Project
API Overview
API Reference
curl -X POST [CLIENT URL] -d "grant_type=client_credentials&client_id=some_client_id&client_secret=some_client_secret" -H content-type=x-www-form-urlencoded -v
Sample OAuth Request:
curl --request POST \
--url https://client.visa/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials \
--data client_id=gtb094fb-8575-4ce5-a10e-5afef11c379d \
--data 'client_secret=fez7-9jtWHVSH*3w'
Sample OAuth Response:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ6NE1femd4Z3lXZE03S2E4QnJSZjVRQ3RGdmxZY19YOEctSi1hYVhzT3lZIn0.eyJleHAiOjE2OTM1MDk5MjMsImlhdCI6MTY5MzUwODEyMywianRpIjoiZDg3NWUwYzAtZjFmNS00ZmVhLTllNzItZmViMGZjOGNhYmMyIiwiaXNzIjoiaHR0cHM6Ly9kaXJlY3RvcnktY2RlLXN0Zy55ZWxsb3dwZXBwZXIuY29tL3JlYWxtcy9kaXJlY3Rvcnktc3RnIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6Imd0YjA5NGZiLTg1NzUtNGNlNS1hMTBlLTVhZmVmMTFjMzc5ZCIsInR5cCI6IkJlYXJlciIsImF6cCI6Imd0YjA5NGZiLTg1NzUtNGNlNS1hMTBlLTVhZmVmMTFjMzc5ZCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIiwiZGVmYXVsdC1yb2xlcy1kaXJlY3Rvcnktc3RnIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwiY2xpZW50SG9zdCI6IjE4Ni4yOC45OS4xNjAiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImNsaWVudElkIjoiZ3RiMDk0ZmItODU3NS00Y2U1LWExMGUtNWFmZWYxMWMzNzlkIiwicHJvZ3JhbV9pZCI6ImJhZjg1NjI0LTNjZjYtNGM1Mi1iOTFmLWI4ZjM0OTNlNzMzMCIsInBhcnRpY2lwYW50X2lkIjoiMDEyYWY3M2YtNDRkOC00YzljLWJiZWUtNjI4YjA3ZmFhZTFjIiwicHJlZmVycmVkX3VzZXJuYW1lIjoic2VydmljZS1hY2NvdW50LWd0YjA5NGZiLTg1NzUtNGNlNS1hMTBlLTVhZmVmMTFjMzc5ZCIsImNsaWVudEFkZHJlc3MiOiIxODYuMjguOTkuMTYwIn0.K82wwbe0vwRhaRiZt5XMCkMxlSPdkykTf0atAB9q4aO-3MG6Gm6rgFjxskNg7keRL1EvNS-GeYW7p9kMidczpW-xL7hyGnZ7ezQE88DTFlt5Sd13lcuXQhdoTFnQIzQRGPdjXPTY75ZsUI3SkP9puKaWfBjuRaT9Vpmo1ojBGa15Zga1pcaE33vRJHYn9G_qiQchzI54jHS1aO73q8448GfwRkFKJL2xAxJYiuKbJ2yFnrhWbbNNdZT0ftDSaX06RGKGi4ktSc7h2WTyktv5Jw5erb9vtoT1zeM9NwW5XjwF0NX9jTleWUOakpv4XovEWQkaXS1RvxDoNbFRrZNtog",
"expires_in": 1800,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "read"
}
Message Level Encryption (MLE) will be used to encrypt the messages that Directory Network Manager exchanges with the Remote Directory.
Message Level Encryption (MLE) allows you to communicate with other parties while helping to prevent uninvolved parties from understanding the communication. MLE can help address the threat of relying on TLS for message security. SSL is designed to provide point-to-point security, which falls short for web/restful services because of a need for end-to-end security. Where multiple intermediary nodes could exist between the two endpoints, MLE would ensure that the message remains encrypted, even during these intermediate "hops" where the traffic itself is decrypted before it arrives the final destination. Both processes involve a mathematical formula (algorithm) and secret data (key).
MLE is required for APIs that primarily deal with sensitive transaction data (financial/non-financial) which could fall into one or several of the following categories:
PII (Personal Identification Information)
PAN (Personal Account Number)
PAI (Personal Account Information)
During the Remote Directory onboarding, Directory Network Manager and the Remote Directory will exchange public keys to cover the flow described below:
As part of the MLE certificate signing process, the implementation manager will need to collect the below fields from the Remote Directory.
There are two certificate pairs required for MLE:
Remote Directory generates the server encryption certificate and provides the CSR for the relevant Key-ID to the Alias Directory platform. Definitions for CSRs and Key-IDs below:
CSR |
Certificate Signing Request is a block of encoded texts used by a CA (Certificate Authority) to create a certificate. |
Key-ID |
The Key-ID is a unique identifier (UID) associated with the remote directory and identifies the associated key-pairs. This Key-ID will be included as a request header in API calls. Key-IDs also allow for a more seamless migration to new MLE certificates when needed. |
Public key for this certificate is stored on the the Alias Directory platform. The Alias Directory platform will encrypt the requests (message payload) using the public key (of Remote Directory); Remote Directory will use the applicable private key stored on their environment to decrypt the payload and process the API request.
The Alias Directory platform generates the client encryption certificate based on the provided information for a particular Key-ID. The public key for this certificate will be provided to the remote directory during the implementation process. The remote directory will use this public key to encrypt the responses (message payload) and return the information to the Alias Directory platform. The Alias Directory platform uses the private key associated with the Key-ID to decrypt this payload and process the API response.
The Key-ID is a GUID generated by the Remote Directory that associates MLE certificates with it, this Key-ID must be sent to the Alias Directory platform along with the CSR (generation process described below) to complete the process.
Remote Directory can use either OpenSSL or Keytool to generate a CSR & private key. The key fields for the CSR are:
Please refer to this Visa Developer encryption guide for more information on MLE and CSR generation.
The remote directory must implement the specifications for Alias Resolution API and Alias Inquiry API to connect with Directory Network Manager. Please see API specifications here.
| API Name | Description |
| Alias Resolution API | This API accepts an Alias for a query and returns a payment credential which can then be used for a push payment. |
| Alias Inquiry API | This API enables clients to check if an Alias or list of Aliases is available for Alias resolution. The response will indicate the Aliases that are available for Alias resolution. |
The current Alias Directory Service connects to remote directories and queries these remote directories during every Resolve or Inquiry API call. With the Alias Metadata feature, the number of API calls to the remote directory can be reduced.
Alias Metadata APIs allow remote directories to store limited info in the Alias Directory such as the alias and preferredFor. Below is an example of a Alias Metadata record
{
"aliases": [
{
"aliasValue": "1234567890",
"aliasType": "PHONE",
"preferredPaymentCredentials": [
{
"type": "CARD",
"preferredFor": [
{
"type": "RECEIVE"
}
]
}
],
"action": "ADD"
}
]
}
During an Alias Resolution API call, if the Alias contains a preferredFor, then Alias Directory Service will query the Remote Directory for the payment credential. If the Alias does not contain a preferredFor, then the Alias Directory will not query the Remote Directory. Using the example above, if an Alias Resolve API contains “1234567890” in the query, then Alias Directory will query the Remote Directory to retrieve the payment credential. If “1234567890” was not found in the Alias Metadata or was not marked as preferred for “RECEIVE”, then the Alias Directory will not query the Remote Directory.
Please contact your Visa representative for more information.