How to Use Batch Processing
Visa Alias Directory Service
Simplify the push payment experience. Link and resolve an Alias to a payment credential.
How to Use Batch Processing
Overview
Alias Directory Service allows participants to submit requests for bulk operations (i.e. Create Alias) using its Batch Processing Service. Using this service, participants can implement use cases such as directory migration, mass Alias creation during go-live phase, and mass deletion.
Client Create a one-time encryption key
Visa
Return encryption key details
Client Create batch file
Client Submit batch process request
Visa Return a batch process ID
Client Check on the batch process status
Client When status is completed, decode and decompress results file
Available Endpoints
| Endpoint | Overview | Details |
|---|---|---|
| Generate Key POST /batchKeys |
Create one-time encryption key. | The one-time key provided in the response is composed of three objects: 1. Key unique ID 2. AES-GCM encryption key 3. AES encryption Initialization Vector A new key must be generated each time the Participant submits a new Batch request. Once the key is used, it will be deactivated. |
| Create Batch Request POST /batches |
Submit a batch request and receive a batch request ID, which can be used to retrieve information about the batch request status. | The operation field indicates which operation will be executed (i.e. CREATE_ALIAS).The data field contains the data to use for the batch operation (e.g., aliasValue, aliasType, profile, paymentCredentials).The data field value must be a compressed, encrypted and base64 encoded file.Alias Directory will process the batch request offline. The status of the batch operation can be retrieved with Get Batch Status. |
| Get Batch Status GET /batches/{batchId} |
Retrieve the status of a specific batch request. | This endpoint provides the status of a batch request and indicates whether the batch request was completed. |
| Get Batch Results GET /batches/{batchId}/result |
Retrieve an output file with the results of the batch request. | This endpoint retrieves a file using the batch ID. The file will indicate the result of each request in the batch request. The data field value will be returned as a compressed and base64 encoded file. |
Available Batch Operations
| Operation | Description |
|---|---|
| CREATE_ALIAS | Create multiple Aliases within Alias Directory. The fields, field format, business validation, and constraints for this batch operation are identical to the Create Alias API with only one exception: If an Alias already exists with a preferred Payment Credential, a new participant creating the same Alias via batch will not be able to take the preference away from the existing preferred Payment Credential. |
| DELETE_ALIAS | Delete multiple Aliases using the Alias IDs within Alias Directory. Business validations and constraints for this batch operation are identical to the Delete Alias API. |
| UPDATE_BANK_PAYMENT_CREDENTIAL | Specific fields for multiple Payment Credentials. The following fields can be updated: - Bank Code - Bank Code Type - Branch Code - Bank Name |
Creating a Batch Processing Input File
Participants must create Batch Processing input files in order to submit Batch processing requests. These files will contain the necessary information for Alias Directory platform to complete the request.
1. Generate One Time Key
Use the Generate Key API to request a new AES one-time key pair.
2. Generate Plain Data
The source data is a plain file formatted in semicolon separated values. Each row within the file is meant to be a single request for the API selected and must follow the structure:
where:
- recordId. Required. A 36 character long unique identifier for this particular request
- requestBody. Optional. JSON formatted string with the data and format required for the operation (CREATE_ALIAS, UPDATE_BANK_PAYMENT_CREDENTIAL).
- pathParams. Optional. JSON formatted string with the parameters required for the operation (DELETE_ALIAS).
Example #1 - Creating Aliases
The following example contains information to create 2 aliases. Please note that the Create Alias operation has a request body but no path parameters.
Example #2 - Deleting Aliases
This next example is to delete 2 aliases. Please note the Delete Alias operation has no request body, but has path parameters.
3. Prepare file to be submitted
Once the plain file has been built, it must be compressed, encrypted and encoded before uploading to the API.
This preparation consists of 3 steps:
- File compression: First, the plain file must be compressed using ZStandard algorithm.
- File encryption: Then, the compressed file must be encrypted with AES-GCM encryption, using the one-time key pair obtained from the Generate Key endpoint.
- File encoding: Finally, the resulting file should be encoded in Base64.
4. Create Batch Request
Below is a sample payload for the Create Batch Request API.
Where:
keyId:Is the id of the previously generated one-time key.data:Is the UTF-8 encoded string generated in previous section.operation:The batch operation. Refer to documentation for more details.
Reading Batch Processing Result File
After the batch process request is completed, the results file can be downloaded. This result file contains the status and response for each individual request sent in the batch request input file.
1. Get Batch Status
Use the Get Batch Status API to obtain the status of a given batch request by using the batch id returned in the Create Batch Request API.
2. Get Batch Results
3. Decode and Decompress Results File
Reading the results file involves:
- File decoding: Decode the Base64 content into a binary file.
- File decompression: Decompress the binary file into the plain results file.