Visa ID and Credential

VICA protects every request at two levels. Caller authentication proves the request comes from you — using either Two-Way SSL (mutual TLS) or an X-Pay-Token (API key + shared secret). Message Level Encryption (MLE) then protects the payload. You choose one caller-authentication method; MLE is required in all environments regardless of that choice.

VICA requires Two-Way SSL (mutual authentication). Unlike one-way TLS, both client and server present and verify certificates during the SSL handshake: the client verifies Visa's server certificate, and Visa verifies the client's certificate before granting access to the requested resource.

To call VICA you must:

1. Obtain a valid client certificate from Visa Developer (see How do I obtain VICA credentials?).
2. Present the client certificate and private key on every request (e.g., --cert / --key with curl, or the equivalent in your HTTP client).

The sandbox secures connections the same way as production, so you exercise mutual authentication from your first call. For step-by-step certificate setup, follow the Visa Developer Two-Way SSL Guide .

As an alternative to Two-Way SSL, VICA supports X-Pay-Token authentication - Visa's API key + shared secret scheme. Instead of presenting a client certificate, you sign each request with your shared secret and send the signature in an x-pay-token header. This suits clients that prefer key-based authentication over managing TLS client certificates. To call VICA with X-Pay-Token:

To call VICA with X-Pay-Token:

1. Obtain your API key and Shared Secret from your project in Visa Developer Platform (see How do I obtain VICA credentials?).
2. Pass the API key as the apikey query parameter on the request URL.
3. Build the x-pay-token header for each request and send it alongside apikey.

For the exact construction rules (resource-path scoping and lexicographic query-string ordering) and language-specific code samples, follow the Visa Developer X-Pay-Token Guide .

MLE still applies. X-Pay-Token authenticates the caller; it does not encrypt the body. Message Level Encryption is still required — see below.

Message Level Encryption (MLE) is required for all Visa ID and Credential API implementations - regardless of whether you authenticate with Two-Way SSL or X-Pay-Token. MLE adds a layer of protection to the message payload itself using asymmetric (public-key) cryptography, so the body is protected independently of the transport.

• Generate the encryption/decryption key pair in each environment (Sandbox, Certification, Production) where you will operate.
• Encrypt request payloads with Visa's public key and decrypt responses with your private key, per the MLE specification.
• Supply the MLE key identifier on requests using the header documented in API Reference.

For setup, follow the Visa Developer Message Level Encryption documentation and tutorial.

1. In Visa Developer Platform (VDP), create a project and add Visa ID and Credential. Existing VTS clients should work with their Visa Representative for setup.
2. Set up one caller-authentication method:
   1. Two-Way SSL - generate or upload your client certificate, or
   2. X-Pay-Token - note your project's API key and Shared Secret.
3. Generate your MLE key pair for each environment.
4. Your Visa Representative configures and confirms your credentials for Certification and Production as part of the Onboarding Lifecycle.

Contact [email protected] or your Visa Representative with credentialing questions.

VICA can call endpoints that you host to deliver asynchronous results: the Request Status Notification (sent when an async request completes) and the Click to Pay Enrollment Attempt Notification (sent on a self-enrollment when you are enabled for Issuer Offered Click to Pay). You register these endpoints in VDP. Because these are inbound calls to your infrastructure, you are responsible for securing and operating the receiver.

When you build a notification receiver, design it to:

• Authenticate the caller - verify the request genuinely originates from Visa before acting on it.
• Respond quickly - acknowledge receipt promptly and process asynchronously; treat the notification as a trigger, not a transaction.
• Be idempotent - the same notification may be delivered more than once. De-duplicate on a stable key (for example, requestTraceId) so repeated deliveries don't cause duplicate side effects.
• Tolerate retries and out-of-order delivery - handle redelivery gracefully and don't assume notifications arrive in send order.
• Fail safe - if you can't process a notification, you can still retrieve the outcome via Request Status within its 7-day validity window.

See the receiver contracts in How to Receive Status Notifications and How to Receive Enrollment Attempt Notifications.

• First Steps - environments, base URLs, and your first authenticated call
• Getting Started - onboarding lifecycle and the path to production
• API Reference - header names, certificate requirements, and schemas
• Implementation Guides - outbound notification receiver contracts
• Errors & Troubleshooting - handling failures and retries