Encryption methods
Learn how Visa Developer uses Field-Level and Message-Level Encryption to protect sensitive data and how to identify the encryption requirements for your APIs.
Overview
Encryption protects sensitive data exchanged with Visa Developer APIs, including transaction data such as personally identifiable information (PII), primary account number (PAN), and personal account information (PAI).
TLS is designed to provide point-to-point security by securing the communications channel. Field-Level Encryption (FLE) and Message-Level Encryption (MLE) provide further security by encrypting the payload to provide end-to-end security.
This guide helps you:
- Discover the encryption methods supported by Visa Developer APIs
- Determine which encryption model is supported or required by your project
- Understand MLE enforcement states and encryption flow
Encryption models used across Visa Developer APIs
Encryption requirements are defined at both the API and endpoint level. A single project may include multiple APIs with different encryption models and enforcement states, so always review product‑specific API documentation to confirm which model applies.
Only certain APIs support Field‑Level Encryption (FLE) or Message‑Level Encryption (MLE), depending on the type and sensitivity of the data handled.
| Encryption model | What is encrypted | Typical usage |
|---|---|---|
| Field-Level Encryption (FLE) | Specific fields in the payload | APIs where only designated elements are sensitive |
| Message-Level Encryption (MLE) | Entire payload | APIs handling highly sensitive transaction data |
Field-Level Encryption (FLE)
Field‑Level Encryption encrypts specific fields within an API request or response payload.
In many APIs, encrypted fields are indicated by an enc prefix in the field name (for example, encPaymentInstrument). This allows clients to identify which values must be encrypted before sending a request.
FLE is configured through the API request schema and does not use the Key IDs required for MLE.
Message-Level Encryption (MLE)
Message‑Level Encryption encrypts the entire API payload. Unlike Field‑Level Encryption (FLE), which encrypts individual fields, MLE encrypts the entire payload, providing end‑to‑end protection of message content.
Visa Developer defines MLE requirements using the following levels:
- Mandatory: MLE is required. Requests must be encrypted, and unencrypted payloads are rejected. This applies consistently across Sandbox, Certification, and Production environments.
- Optional: MLE may be either enforced or not enforced. In Sandbox, you can toggle the enforcement state yourself. In Certification and Production, contact a Visa representative. Only a Visa Admin can toggle the enforcement state in higher environments.
- Not applicable: MLE is not supported for the API or endpoint.
Notes:
- If MLE is mandatory, you must implement encryption before making API calls.
- If an API is marked as Mixed, the endpoints under that API have different MLE requirements and must be reviewed individually.
Review requirements and learn how to implement Message-Level Encryption (MLE) for your APIs.
How MLE works
MLE on Visa Developer provides payload‑level security by encrypting message data in addition to transport‑layer protection. MLE operates on top of SSL/TLS and protects sensitive request and response payloads end-to-end.
MLE uses a hybrid encryption model that combines symmetric and asymmetric cryptography. Message payloads are encrypted using Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) with 128‑bit or 256‑bit keys. The encryption and exchange of keys is supported using RSA with Optimal Asymmetric Encryption Padding (OAEP) and a 2048‑bit key size. MLE is implemented using the JSON Web Encryption (JWE) standard.
Request and response encryption flow
The client side and server side each have a key pair and certificate that are used to encrypt and decrypt request and response payloads.
- Request flow: The client encrypts the request payload using the server (Visa) public encryption key from the server’s certificate. The server (Visa) decrypts the payload using its corresponding private key before processing the API request.
- Response flow: Visa encrypts the response payload using the client’s public encryption key. The client decrypts the payload using its corresponding private key before processing the API response.
MLE key IDs and certificates
The MLE client certificate and MLE server certificate used in a transaction are identified by an MLE Key ID. You generate an MLE Key ID before requesting an MLE client certificate. Visa then issues an MLE client certificate and MLE server certificate associated with that MLE Key ID.
When the MLE certificates are about to expire, you must generate a new MLE Key ID and obtain new MLE certificates. The MLE Key ID is not reused for another set of MLE certificates.
The following diagram illustrates the high‑level MLE workflow for request and response encryption and decryption.
MLE tutorial
Open the tutorial video to learn how MLE works across Visa Developer and how it fits into the client go‑live journey.
In this tutorial, you will learn how to:
- Determine when MLE is required by reviewing enforcement levels
- Identify the Key ID used for encrypted API calls
- Select the correct CSR option for your environment
- Understand how Visa and client certificates are used for request and response encryption
- Prepare to implement MLE across Sandbox, Certification, and Production environments
