The table below lists all use cases covered in this guide with their classification.
Mandatory — These use cases form the minimum compliant implementation.
Optional — These use cases extend the core integration.
Conditional — These use cases are required only when the SRCi supports a specific capability.
| Use Case | Title | Description | Classification |
| UC1 | Returning Consumer — Visa identity verification, no step-up | A recognized consumer completes checkout seamlessly after Visa confirms their identity. No additional authentication is required. | Mandatory |
| UC2 | Returning Consumer — Visa identity verification, 3DS step-up | A recognized consumer is asked to complete a 3DS challenge before checkout can proceed. The SRCi must be ready to handle this whenever Visa's risk engine triggers it. | Mandatory |
| UC3 | Returning Consumer — Visa identity verification, CVV2 step-up | A recognized consumer is asked to re-enter their CVV2 before checkout can proceed. Like UC2, this is triggered by Visa's risk engine and is not within the SRCi's control. | Mandatory |
| UC4 | Returning Consumer — Federated identity verification, no step-up | A recognized consumer completes checkout where identity was validated by the SRCi or a third-party provider rather than Visa's OTP flow. No step-up required. | Optional |
| UC5 | Returning Consumer — Federated identity verification, step-up | A recognized consumer using federated identity is asked to complete a step-up challenge before checkout proceeds. | Optional |
| UC6 | Returning Consumer — Add a new card | A recognized consumer adds a new card to their profile during checkout. Whether step-up is subsequently required depends on Visa's risk assessment after enrollment. | Mandatory |
| UC7 | New Consumer Enrollment during checkout | A first-time consumer enrolls a card with CVV2 and completes their first purchase in a single flow. This is the entry point for all new Click to Pay users. | Mandatory |
| UC8 | SRCi requests own token after checkout | After a successful checkout, the SRCi requests a token bound to its own Token Requestor ID for use in future sessions. Required when the SRCi supports SRCi-bound token flow. | Conditional |
| UC9 | SRCi requests DPA token after checkout | After a successful checkout, the SRCi requests a Card on File token tied to the DPA. Required when the DPA supports Card on File token enrollment. | Conditional |
| UC10 | Returning Consumer Checkout — using SRCi-Bound or DPA-Bound token | A consumer whose card has been enrolled as an SRCi-bound or DPA-bound token checks out directly, bypassing identity steps. Required if the SRCi implements UC8 or UC9. | Conditional |
| UC11 | Card Enrollment — with CVV2 | The SRCi enrolls a consumer's card with CVV2 on their behalf, enabling frictionless first checkout. Required when the SRCi supports SRCi-initiated card enrollment. | Conditional |
| UC12 | Card Enrollment — without CVV2 | The SRCi enrolls a consumer's card without CVV2, with step-up required on first use. Required alongside UC11 — an SRCi cannot support one without the other. | Conditional |
A recognized consumer completes checkout seamlessly after Visa confirms their identity. No additional authentication is required.
Classification: Mandatory
This use case covers the core returning consumer checkout flow where Visa validates the consumer's identity via OTP and its risk engine determines no step-up authentication is required. This is the baseline flow that every SRCi implementation must support. A Visa-issued idToken is returned after OTP validation and used to retrieve the consumer's enrolled card list, after which checkout is completed and the payment payload is returned.
Key characteristics:
The following diagram illustrates the complete flow for this use case:
Endpoint: POST /identities/lookup
The SRCi submits the consumer's email or phone to determine whether an existing Visa Click to Pay profile is present. If found (consumerPresent1: true), an idLookupSessionId is returned to initiate identity validation. If not found (consumerPresent1: false), redirect the consumer to card enrollment (UC7).
Request:
Start a Project
API Overview
API Reference
{
"consumerIdentity": {
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"identityValue": "{{emailOrPhone}}"
}
}
Response:
{
"consumerPresent1": true,
"consumerStatus": "ACTIVE",
"idLookupSessionId": "{{idLookupSessionId}}"
}
Implementation notes:
Endpoint: POST /identities/validation/initiate
Submits the idLookupSessionId to trigger Visa sending a One-Time Passcode to the consumer's registered channel. The response includes a masked representation of the delivery channel and an idValidationSessionId for Step 2b.
Request:
{
"idLookupSessionId": "{{idLookupSessionId}}"
}
Response:
Response:
{
"idValidationSessionId": "{{idValidationSessionId}}",
"maskedValidationChannel": {
"validationChannelId": "{{validationChannelId}}",
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"maskedValidationChannel": "{{maskedChannel}}"
}
}
Implementation notes:
Endpoint: POST /identities/validation/complete
The consumer submits the OTP; the SRCi forwards it with the idValidationSessionId. On success, Visa returns a signed idToken representing the verified consumer identity.
Request:
{
"idValidationSessionId": "{{idValidationSessionId}}",
"validationData": "{{otp}}"
}
Response:
{
"idToken": "{{idToken}}"
}
Implementation notes:
Endpoint: POST /profiles/prepare
Submits the Visa-issued idToken to retrieve the consumer's enrolled cards. Returns a srcCorrelationId that must be carried forward in all subsequent calls in this session.
Request:
{
"srciTransactionId": "{{srciTransactionId}}",
"idTokens": ["{{idToken}}"],
"srcDpaId": "{{srcDpaId}}"
}
Response:
{
"srcCorrelationId": "{{srcCorrelationId}}",
"profiles": [{
"maskedCards": [{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "{{descriptorName}}",
"artUri": "{{cardArtUri}}"
},
"dateOfCardLastUsed": "{{dateOfCardLastUsed}}"
}]
}]
}
Implementation notes:
Endpoint: POST /transaction/credentials
Initiates checkout using the selected srcDigitalCardId. Visa's risk engine determines no step-up is required and returns the encrypted payment payload. The payloadTypeIndicatorCheckout field controls whether the payload is returned inline (FULL) or via a separate GET call (SUMMARY).
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
}
}
}
Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"maskedCard": {
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}",
"digitalCardData": { "status": "ACTIVE" }
},
"assuranceData": { "eci": "07" },
"encryptedPayload": "{{encryptedPayload}}",
"enrollmentReferenceData": "{{enrollmentReferenceData}}"
}
}
Implementation notes:
Endpoint: GET /transaction/credentials
Only required when payloadTypeIndicatorCheckout = SUMMARY in the Step 4 response. Retrieves the full encrypted payment payload.
Request:
GET /transaction/credentials
?srcCorrelationId={{srcCorrelationId}}
Response:
{
"payloadResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"assuranceData": { "eci": "07" },
"encryptedPayload": "{{encryptedPayload}}"
}
}
Implementation Notes:
Endpoint: POST /confirmations
After the transaction completes — regardless of outcome — notify Visa of the result. Required for every transaction.
Request:
{
"srcCorrelationId": "{{srcCorrelationId}}",
"confirmationData2": {
"checkoutEventType": "01",
"confirmationStatus": "01",
"confirmationTimestamp": "{{unixTimestamp}}"
}
}
Implementation notes:
A recognized consumer is asked to complete a 3DS challenge before checkout can proceed. The SRCi must be ready to handle this whenever Visa's risk engine triggers it.
Classification: Mandatory
This use case covers the returning consumer checkout flow where Visa's risk engine determines that 3DS step-up authentication is required before the payment payload is released. Steps 1–3 are identical to UC1 — identity lookup, OTP validation, and profile retrieval. At checkout, Visa returns a hosted authentication URI rather than a payload. The SRCi launches this URI, the consumer completes 3DS authentication, and the SRCi re-submits checkout with the returned assuranceData. The authenticated payload includes ECI 05.
Key characteristics:
The following diagram illustrates the complete flow for this use case:
Endpoint: POST /identities/lookup
The SRCi submits the consumer's email or phone to determine whether an existing Visa Click to Pay profile is present. If found (consumerPresent1: true), an idLookupSessionId is returned to initiate identity validation. If not found (consumerPresent1: false), redirect the consumer to card enrollment (UC7).
Request:
{
"consumerIdentity": {
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"identityValue": "{{emailOrPhone}}"
}
}
Response:
{
"consumerPresent1": true,
"consumerStatus": "ACTIVE",
"idLookupSessionId": "{{idLookupSessionId}}"
}
Implementation notes:
Endpoint: POST /identities/validation/initiate
Submits the idLookupSessionId to trigger Visa sending a One-Time Passcode to the consumer's registered channel. The response includes a masked representation of the delivery channel and an idValidationSessionId for Step 2b.
Request:
{
"idLookupSessionId": "{{idLookupSessionId}}"
}
Response:
Response:
{
"idValidationSessionId": "{{idValidationSessionId}}",
"maskedValidationChannel": {
"validationChannelId": "{{validationChannelId}}",
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"maskedValidationChannel": "{{maskedChannel}}"
}
}
Implementation notes:
Endpoint: POST /identities/validation/complete
The consumer submits the OTP; the SRCi forwards it with the idValidationSessionId. On success, Visa returns a signed idToken representing the verified consumer identity.
Request:
{
"idValidationSessionId": "{{idValidationSessionId}}",
"validationData": "{{otp}}"
}
Response:
{
"idToken": "{{idToken}}"
}
Implementation notes:
Endpoint: POST /profiles/prepare
Submits the Visa-issued idToken to retrieve the consumer's enrolled cards. Returns a srcCorrelationId that must be carried forward in all subsequent calls in this session.
Request:
{
"srciTransactionId": "{{srciTransactionId}}",
"idTokens": ["{{idToken}}"],
"srcDpaId": "{{srcDpaId}}"
}
Response:
{
"srcCorrelationId": "{{srcCorrelationId}}",
"profiles": [{
"maskedCards": [{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "{{descriptorName}}",
"artUri": "{{cardArtUri}}"
},
"dateOfCardLastUsed": "{{dateOfCardLastUsed}}"
}]
}]
}
Implementation notes:
Endpoint: POST /transaction/credentials
SRCi submits checkout with payloadRequested: AUTHENTICATED. Visa's risk engine determines 3DS is required and returns a response without an encrypted payload — instead returning uriData to launch the hosted step-up UI.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
},
"authenticationPreferences": { "payloadRequested": "AUTHENTICATED" }
}
}
Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"maskedCard": {
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"pendingEvents": ["PENDING_CARDHOLDER_AUTHENTICATION"],
"authenticationMethods": [{
"authenticationMethodType": "SRCS_HOSTED_AUTHENTICATION",
"uriData": { "uri": "{{stepUpUri}}", "uriType": "WEB_URI" }
}]
}
}
}
}
Implementation notes:
No API call — UI event handling
The SRCi opens uriData.uri in a popup window. The consumer completes the authentication challenge — 3DS (Visa Secure), Visa Payment Passkey, or CVV2 — in the Visa-hosted experience. Visa returns assuranceData via postMessage on completion.
Implementation notes:
Endpoint: POST /transaction/credentials
Re-submits checkout with assuranceData from Step 5. Visa validates the 3DS result and releases the authenticated payment payload with ECI 05.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"assuranceData": { "verificationData": ["{{verificationData}}"] },
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
},
"authenticationPreferences": { "payloadRequested": "AUTHENTICATED" }
}
}
Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"maskedCard": {
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}",
"digitalCardData": { "status": "ACTIVE" }
},
"assuranceData": { "eci": "05" },
"encryptedPayload": "{{encryptedPayload}}",
"enrollmentReferenceData": "{{enrollmentReferenceData}}"
}
}
Implementation notes:
Endpoint: GET /transaction/credentials
Only required when payloadTypeIndicatorCheckout = SUMMARY in Step 6. Retrieves the full authenticated payload.
Request:
GET /transaction/credentials
?srcCorrelationId={{srcCorrelationId}}
Response:
{
"payloadResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"assuranceData": { "eci": "05" },
"encryptedPayload": "{{encryptedPayload}}"
}
}
Implementation Notes:
Endpoint: POST /confirmations
After the authenticated transaction completes — regardless of outcome — notify Visa of the final status.
Request:
{
"srcCorrelationId": "{{srcCorrelationId}}",
"confirmationData2": {
"checkoutEventType": "01",
"confirmationStatus": "01",
"confirmationTimestamp": "{{unixTimestamp}}"
}
}
Implementation notes:
A recognized consumer is asked to re-enter their CVV2 before checkout can proceed. Like UC2, this is triggered by Visa's risk engine and is not within the SRCi's control.
Classification: Mandatory
This use case covers the returning consumer checkout flow where Visa's risk engine determines that CVV2 step-up authentication is required. Steps 1–3 are identical to UC1 and UC2. At checkout, Visa returns a hosted authentication URI for a CVV2 challenge. The SRCi launches the URI, the consumer enters their CVV2, and the SRCi re-submits checkout with the returned assuranceData. The payload is returned with ECI 07.
Key characteristics:
The following diagram illustrates the complete flow for this use case:
Endpoint: POST /identities/lookup
The SRCi submits the consumer's email or phone to determine whether an existing Visa Click to Pay profile is present. If found (consumerPresent1: true), an idLookupSessionId is returned to initiate identity validation. If not found (consumerPresent1: false), redirect the consumer to card enrollment (UC7).
Request:
{
"consumerIdentity": {
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"identityValue": "{{emailOrPhone}}"
}
}
Response:
{
"consumerPresent1": true,
"consumerStatus": "ACTIVE",
"idLookupSessionId": "{{idLookupSessionId}}"
}
Implementation notes:
Endpoint: POST /identities/validation/initiate
Submits the idLookupSessionId to trigger Visa sending a One-Time Passcode to the consumer's registered channel. The response includes a masked representation of the delivery channel and an idValidationSessionId for Step 2b.
Request:
{
"idLookupSessionId": "{{idLookupSessionId}}"
}
Response:
Response:
{
"idValidationSessionId": "{{idValidationSessionId}}",
"maskedValidationChannel": {
"validationChannelId": "{{validationChannelId}}",
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"maskedValidationChannel": "{{maskedChannel}}"
}
}
Implementation notes:
Endpoint: POST /identities/validation/complete
The consumer submits the OTP; the SRCi forwards it with the idValidationSessionId. On success, Visa returns a signed idToken representing the verified consumer identity.
Request:
{
"idValidationSessionId": "{{idValidationSessionId}}",
"validationData": "{{otp}}"
}
Response:
{
"idToken": "{{idToken}}"
}
Implementation notes:
Endpoint: POST /profiles/prepare
Submits the Visa-issued idToken to retrieve the consumer's enrolled cards. Returns a srcCorrelationId that must be carried forward in all subsequent calls in this session.
Request:
{
"srciTransactionId": "{{srciTransactionId}}",
"idTokens": ["{{idToken}}"],
"srcDpaId": "{{srcDpaId}}"
}
Response:
{
"srcCorrelationId": "{{srcCorrelationId}}",
"profiles": [{
"maskedCards": [{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "{{descriptorName}}",
"artUri": "{{cardArtUri}}"
},
"dateOfCardLastUsed": "{{dateOfCardLastUsed}}"
}]
}]
}
Implementation notes:
Endpoint: POST /transaction/credentials
SRCi submits the initial checkout request. Visa's risk engine determines CVV2 step-up is required and returns uriData to launch the hosted CVV2 authentication experience.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srcDpaId": "{{srcDpaId}}",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
},
"authenticationPreferences": { "payloadRequested": "{{payloadRequested}}" }
}
}
Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"maskedCard": {
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"pendingEvents": ["PENDING_CARDHOLDER_AUTHENTICATION"],
"authenticationMethods": [{
"authenticationMethodType": "SRCS_HOSTED_AUTHENTICATION",
"uriData": { "uri": "{{stepUpUri}}", "uriType": "WEB_URI" }
}]
}
}
}
}
Implementation notes:
No API call — UI event handling
The SRCi opens uriData.uri in a popup window. The consumer completes the authentication challenge — 3DS (Visa Secure), Visa Payment Passkey, or CVV2 — in the Visa-hosted experience. Visa returns assuranceData via postMessage on completion.
Implementation notes:
Endpoint: POST /transaction/credentials
Re-submits checkout with assuranceData from Step 5. Visa validates and releases the encrypted payment payload with ECI 07.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srcDpaId": "{{srcDpaId}}",
"assuranceData": { "verificationData": ["{{verificationData}}"] },
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
},
"authenticationPreferences": { "payloadRequested": "{{payloadRequested}}" }
}
}
Response (payloadTypeIndicatorCheckout = FULL):
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"maskedCard": {
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}",
"digitalCardData": { "status": "ACTIVE" }
},
"assuranceData": { "eci": "07" },
"encryptedPayload": "{{encryptedPayload}}",
"enrollmentReferenceData": "{{enrollmentReferenceData}}"
}
}
Implementation notes:
Endpoint: GET /transaction/credentials
Only required when payloadTypeIndicatorCheckout = SUMMARY in the Step 6 checkout response.
Request:
GET /transaction/credentials
?srcCorrelationId={{srcCorrelationId}}
Response:
{
"encryptedPayload": "{{encryptedPayload}}",
"dynamicData": [{
"dynamicDataValue": "{{tavv}}",
"dynamicDataType": "CARD_APPLICATION_CRYPTOGRAM_LONG_FORM",
"dynamicDataExpiration": "{{dynamicDataExpiration}}"
}],
"srcCorrelationId": "{{srcCorrelationId}}"
}
Implementation Notes:
Endpoint: POST /confirmations
After authorization, report the transaction outcome to Visa. Required regardless of authorization result.
Request:
{
"srcCorrelationId": "{{srcCorrelationId}}",
"confirmationData2": {
"checkoutEventType": "01",
"confirmationStatus": "01",
"confirmationTimestamp": "{{unixTimestamp}}"
}
}
Implementation notes:
A recognized consumer completes checkout using federated identity validation performed by the SRCi or a third-party IDP. No additional authentication is required.
Classification: Optional
This use case covers the returning consumer checkout flow where identity validation is performed by the SRCi or a third-party Identity Provider (IDP) rather than by Visa. The SRCi obtains a federated idToken from the IDP and submits it to Visa to retrieve the consumer's enrolled cards. Visa's risk engine determines no step-up authentication is required, and the payment payload is returned.
Key characteristics:
The following diagram illustrates the complete flow for this use case:
Endpoint: POST /identities/lookup
The SRCi submits the consumer's email or phone to determine whether an existing Visa Click to Pay profile is present. If found (consumerPresent1: true), an idLookupSessionId is returned. For federated identity flows, this session ID confirms profile existence but identity validation will be performed externally.
Request:
{
"consumerIdentity": {
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"identityValue": "{{emailOrPhone}}"
}
}
Response:
{
"consumerPresent1": true,
"consumerStatus": "ACTIVE",
"idLookupSessionId": "{{idLookupSessionId}}"
}
Implementation notes:
External Process
The SRCi or third-party IDP validates the consumer's identity using their own authentication mechanisms (e.g., username/password, biometrics, SSO). Upon successful validation, the IDP issues a federated idToken that represents the verified consumer identity.
Implementation notes:
Endpoint: POST /profiles/prepare
Submits the federated idToken to retrieve the consumer's enrolled cards. Returns a srcCorrelationId that must be carried forward in all subsequent calls in this session.
Request:
{
"srciTransactionId": "{{srciTransactionId}}",
"idTokens": ["{{federatedIdToken}}"],
"srcDpaId": "{{srcDpaId}}"
}
Response:
{
"srcCorrelationId": "{{srcCorrelationId}}",
"profiles": [{
"maskedCards": [{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "{{descriptorName}}",
"artUri": "{{cardArtUri}}"
},
"dateOfCardLastUsed": "{{dateOfCardLastUsed}}"
}]
}]
}
Implementation notes:
Endpoint: POST /transaction/credentials
Initiates checkout using the selected srcDigitalCardId. Visa's risk engine determines no step-up is required and returns the encrypted payment payload.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
}
}
}
Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"maskedCard": {
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}",
"digitalCardData": { "status": "ACTIVE" }
},
"assuranceData": { "eci": "07" },
"encryptedPayload": "{{encryptedPayload}}",
"enrollmentReferenceData": "{{enrollmentReferenceData}}"
}
}
Implementation notes:
Endpoint: GET /transaction/credentials
Only required when payloadTypeIndicatorCheckout = SUMMARY in the Step 4 response. Retrieves the full encrypted payment payload.
Request:
GET /transaction/credentials
?srcCorrelationId={{srcCorrelationId}}
Response:
{
"payloadResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"assuranceData": { "eci": "07" },
"encryptedPayload": "{{encryptedPayload}}"
}
}
Implementation Notes:
Endpoint: POST /confirmations
After the transaction completes — regardless of outcome — notify Visa of the result. Required for every transaction.
Request:
{
"srcCorrelationId": "{{srcCorrelationId}}",
"confirmationData2": {
"checkoutEventType": "01",
"confirmationStatus": "01",
"confirmationTimestamp": "{{unixTimestamp}}"
}
}
Implementation notes:
A recognized consumer completes checkout using federated identity validation, but Visa's risk engine requires additional authentication via step-up challenge.
Classification: Optional
This use case covers the returning consumer checkout flow where identity validation is performed by the SRCi or a third-party IDP, but Visa's risk engine determines that step-up authentication is required before releasing the payment payload. The consumer must complete a Visa-hosted authentication challenge (3DS or Visa Passkey/FIDO) before checkout can proceed.
Key characteristics:
The following diagram illustrates the complete flow for this use case:
Endpoint: POST /identities/lookup
The SRCi submits the consumer's email or phone to determine whether an existing Visa Click to Pay profile is present. If found (consumerPresent1: true), an idLookupSessionId is returned.
Request:
{
"consumerIdentity": {
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"identityValue": "{{emailOrPhone}}"
}
}
Response:
{
"consumerPresent1": true,
"consumerStatus": "ACTIVE",
"idLookupSessionId": "{{idLookupSessionId}}"
}
Implementation notes:
External Process
The SRCi or third-party IDP validates the consumer's identity using their own authentication mechanisms. Upon successful validation, the IDP issues a federated idToken.
Implementation notes:
Endpoint: POST /profiles/prepare
Submits the federated idToken to retrieve the consumer's enrolled cards. Returns a srcCorrelationId that must be carried forward in all subsequent calls.
Request:
{
"srciTransactionId": "{{srciTransactionId}}",
"idTokens": ["{{federatedIdToken}}"],
"srcDpaId": "{{srcDpaId}}"
}
Response:
{
"srcCorrelationId": "{{srcCorrelationId}}",
"profiles": [{
"maskedCards": [{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "{{descriptorName}}",
"artUri": "{{cardArtUri}}"
},
"dateOfCardLastUsed": "{{dateOfCardLastUsed}}"
}]
}]
}
Implementation notes:
Endpoint: POST /transaction/credentials
Initiates checkout using the selected srcDigitalCardId. Visa's risk engine determines step-up is required and returns uriData instead of the payment payload.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
}
}
}
Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"maskedCard": {
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}"
},
"pendingEvents": ["PENDING_CARDHOLDER_AUTHENTICATION"],
"uriData": {
"uri": "{{visaHostedStepUpUrl}}",
"method": "GET"
}
}
}
Implementation notes:
Client-Side Implementation
Launch the Visa-hosted step-up UI using the uri from the uriData response. The consumer completes the authentication challenge (3DS or Visa Passkey/FIDO) in a popup window or iframe.
Implementation notes:
Endpoint: POST /transaction/credentials
After the consumer completes step-up authentication, submit the assuranceData received via postMessage to retrieve the encrypted payment payload.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"assuranceData": "{{assuranceDataFromPostMessage}}",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
}
}
}
Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"maskedCard": {
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}",
"digitalCardData": { "status": "ACTIVE" }
},
"assuranceData": { "eci": "05" },
"encryptedPayload": "{{encryptedPayload}}",
"enrollmentReferenceData": "{{enrollmentReferenceData}}"
}
}
Implementation notes:
Endpoint: GET /transaction/credentials
Only required when payloadTypeIndicatorCheckout = SUMMARY in the Step 5 response.
Request:
GET /transaction/credentials
?srcCorrelationId={{srcCorrelationId}}
Response:
{
"payloadResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"assuranceData": { "eci": "05" },
"encryptedPayload": "{{encryptedPayload}}"
}
}
Implementation Notes:
Endpoint: POST /confirmations
After the transaction completes — regardless of outcome — notify Visa of the result. Required for every transaction.
Request:
{
"srcCorrelationId": "{{srcCorrelationId}}",
"confirmationData2": {
"checkoutEventType": "01",
"confirmationStatus": "01",
"confirmationTimestamp": "{{unixTimestamp}}"
}
}
Implementation notes:
A recognized consumer with an existing Visa Click to Pay profile adds a new card during checkout and completes the transaction.
Classification: Mandatory
This use case covers the scenario where a returning consumer with an existing Visa Click to Pay profile chooses to add and use a new card during checkout. The consumer completes identity validation (Steps 1-3 identical to UC1), then provides new card details which are enrolled via the POST /cards endpoint. Depending on whether CVV2 is provided and Visa's risk assessment, step-up authentication may or may not be required.
Key characteristics:
The following diagram illustrates the complete flow for this use case:
Endpoint: POST /identities/lookup
The SRCi submits the consumer's email or phone to determine whether an existing Visa Click to Pay profile is present.
Request:
{
"consumerIdentity": {
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"identityValue": "{{emailOrPhone}}"
}
}
Response:
{
"consumerPresent1": true,
"consumerStatus": "ACTIVE",
"idLookupSessionId": "{{idLookupSessionId}}"
}
Implementation Notes:
Endpoint: POST /identities/validation/initiate
Submits the idLookupSessionId to trigger Visa sending a One-Time Passcode to the consumer's registered channel.
Request:
{
"idLookupSessionId": "{{idLookupSessionId}}"
}
Response:
{
"idValidationSessionId": "{{idValidationSessionId}}",
"maskedValidationChannel": {
"validationChannelId": "{{validationChannelId}}",
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"maskedValidationChannel": "{{maskedChannel}}"
}
}
Implementation Notes:
Endpoint: POST /identities/validation/complete
The consumer submits the OTP; the SRCi forwards it with the idValidationSessionId. On success, Visa returns a signed idToken.
Request:
{
"idValidationSessionId": "{{idValidationSessionId}}",
"validationData": "{{otp}}"
}
Response:
{
"idToken": "{{idToken}}"
}
Implementation Notes:
Endpoint: POST /profiles/prepare
Submits the Visa-issued idToken to retrieve the consumer's enrolled cards. Returns a srcCorrelationId that must be carried forward in all subsequent calls.
Request:
{
"srciTransactionId": "{{srciTransactionId}}",
"idTokens": ["{{idToken}}"],
"srcDpaId": "{{srcDpaId}}"
}
Response:
{
"srcCorrelationId": "{{srcCorrelationId}}",
"profiles": [{
"maskedCards": [{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "{{descriptorName}}",
"artUri": "{{cardArtUri}}"
},
"dateOfCardLastUsed": "{{dateOfCardLastUsed}}"
}]
}]
}
Implementation Notes:
Endpoint: POST /cards
Enrolls the new card into the consumer's Visa Click to Pay profile. The card status and whether step-up is required depends on whether CVV2 is provided.
Request:
{
"cardData": {
"accountNumber": "{{pan}}",
"expirationDate": {
"month": "{{mm}}",
"year": "{{yyyy}}"
},
"cardSecurityCode": "{{cvv2}}"
},
"consumerIdentity": {
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"identityValue": "{{emailOrPhone}}"
}
}
Response (with CVV2):
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"maskedCard": {
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "{{descriptorName}}"
}
}
}
Response (without CVV2):
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"maskedCard": {
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "{{descriptorName}}"
}
},
"pendingEvents": ["PENDING_CARDHOLDER_AUTHENTICATION"]
}
Implementation notes:
Endpoint: POST /transaction/credentials
If CVV2 was provided and Visa's risk engine approves, checkout proceeds without step-up and the encrypted payment payload is returned.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
}
}
}
Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"maskedCard": {
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}"
},
"assuranceData": { "eci": "07" },
"encryptedPayload": "{{encryptedPayload}}"
}
}
Implementation notes:
Endpoint: POST /transaction/credentials (twice)
If CVV2 was not provided or Visa's risk engine requires step-up, the first checkout call returns uriData. The consumer completes the Visa-hosted authentication challenge, then a second checkout call with assuranceData retrieves the payload.
First Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
}
}
}
First Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"pendingEvents": ["PENDING_CARDHOLDER_AUTHENTICATION"],
"uriData": {
"uri": "{{visaHostedStepUpUrl}}",
"method": "GET"
}
}
}
Client-Side: Launch the Visa-hosted step-up UI using the uri. Listen for window.postMessage containing assuranceData.
Second Request (after step-up):
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"assuranceData": "{{assuranceDataFromPostMessage}}",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
}
}
}
Second Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"maskedCard": {
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}"
},
"assuranceData": { "eci": "05" },
"encryptedPayload": "{{encryptedPayload}}"
}
}
Implementation notes:
Endpoint: GET /transaction/credentials
Only required when payloadTypeIndicatorCheckout = SUMMARY in the Step 5 response.
Request:
GET /transaction/credentials
?srcCorrelationId={{srcCorrelationId}}
Implementation Notes:
Endpoint: POST /confirmations
After the transaction completes — regardless of outcome — notify Visa of the result. Required for every transaction.
Request:
{
"srcCorrelationId": "{{srcCorrelationId}}",
"confirmationData2": {
"checkoutEventType": "01",
"confirmationStatus": "01",
"confirmationTimestamp": "{{unixTimestamp}}"
}
}
Implementation notes:
A new consumer without an existing Visa Click to Pay profile enrolls their first card during checkout and completes the transaction.
Classification: Mandatory
This use case covers the guest checkout scenario where a consumer without an existing Visa Click to Pay profile enrolls their first card during checkout. The identity lookup returns consumerPresent1: false, prompting card enrollment via the POST /cards endpoint. The consumer must accept Visa Click to Pay Terms and Conditions during enrollment. Depending on whether CVV2 is provided and Visa's risk assessment, step-up authentication may or may not be required.
Key characteristics:
The following diagram illustrates the complete flow for this use case:
Endpoint: POST /identities/lookup
The SRCi submits the consumer's email or phone to determine whether an existing Visa Click to Pay profile is present. For new consumers, the response returns consumerPresent1: false.
Request:
{
"consumerIdentity": {
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"identityValue": "{{emailOrPhone}}"
}
}
Response:
{
"consumerPresent1": false
}
Implementation notes:
Endpoint: POST /cards
Enrolls the consumer's first card, which automatically creates their Visa Click to Pay profile. The consumer must accept Terms and Conditions before enrollment. The card status and whether step-up is required depends on whether CVV2 is provided.
Request:
{
"cardData": {
"accountNumber": "{{pan}}",
"expirationDate": {
"month": "{{mm}}",
"year": "{{yyyy}}"
},
"cardSecurityCode": "{{cvv2}}"
},
"consumerIdentity": {
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"identityValue": "{{emailOrPhone}}"
}
}
Response (with CVV2):
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"maskedCard": {
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "{{descriptorName}}"
}
}
}
Response (without CVV2):
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"maskedCard": {
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "{{descriptorName}}"
}
},
"pendingEvents": ["PENDING_CARDHOLDER_AUTHENTICATION"]
}
Implementation notes:
Endpoint: POST /transaction/credentials
If CVV2 was provided and Visa's risk engine approves, checkout proceeds without step-up and the encrypted payment payload is returned.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
}
}
}
Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"maskedCard": {
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}"
},
"assuranceData": { "eci": "07" },
"encryptedPayload": "{{encryptedPayload}}"
}
}
Implementation notes:
Endpoint: POST /transaction/credentials (twice)
If CVV2 was not provided or Visa's risk engine requires step-up, the first checkout call returns uriData. The consumer completes the Visa-hosted authentication challenge, then a second checkout call with assuranceData retrieves the payload.
First Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
}
}
}
First Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"pendingEvents": ["PENDING_CARDHOLDER_AUTHENTICATION"],
"uriData": {
"uri": "{{visaHostedStepUpUrl}}",
"method": "GET"
}
}
}
Client-Side: Launch the Visa-hosted step-up UI using the uri. Listen for window.postMessage containing assuranceData.
Second Request (after step-up):
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"assuranceData": "{{assuranceDataFromPostMessage}}",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
}
}
}
Second Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"maskedCard": {
"srcDigitalCardId": "{{srcDigitalCardId}}",
"panLastFour": "{{panLastFour}}"
},
"assuranceData": { "eci": "05" },
"encryptedPayload": "{{encryptedPayload}}"
}
}
Implementation notes:
Endpoint: GET /transaction/credentials
Only required when payloadTypeIndicatorCheckout = SUMMARY in the Step 3 response.
Request:
GET /transaction/credentials
?srcCorrelationId={{srcCorrelationId}}
Implementation Notes:
Endpoint: POST /confirmations
After the transaction completes — regardless of outcome — notify Visa of the result. Required for every transaction.
Request:
{
"srcCorrelationId": "{{srcCorrelationId}}",
"confirmationData2": {
"checkoutEventType": "01",
"confirmationStatus": "01",
"confirmationTimestamp": "{{unixTimestamp}}"
}
}
Implementation notes:
After a successful checkout, the SRCi requests a partner-bound token for streamlined future transactions within their own ecosystem.
Classification: Optional
This use case covers the post-checkout token enrollment flow where the SRCi requests a partner-bound token (SRCi token) for the card used in a successful checkout. This token is bound to the SRCi and can be used for streamlined future checkouts within the SRCi's ecosystem without requiring full identity validation. The enrollmentReferenceData from the checkout response must be used within 24 hours.
Key characteristics:
The following diagram illustrates the complete flow for this use case:
Endpoint: POST /cards
Submits the enrollmentReferenceData from a successful checkout to create an SRCi-bound token. The serviceId field must be set to PARTNER_TOKEN to indicate this is an SRCi token enrollment.
Request:
{
"serviceId": "PARTNER_TOKEN",
"enrollmentReferenceData": {
"id": "{{enrollmentReferenceDataId}}",
"type": "{{enrollmentReferenceDataType}}"
}
}
Response:
{
"srcDigitalCardId": "{{srciTokenId}}",
"maskedCard": {
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "{{descriptorName}}"
}
}
}
Implementation Notes:
Once the SRCi token is created, it can be used for streamlined checkout flows:
After a successful checkout, the SRCi requests a DPA-bound token (Card-on-File) for use across multiple merchants within the DPA ecosystem.
Classification: Optional
This use case covers the post-checkout token enrollment flow where the SRCi requests a DPA-bound token (also known as Card-on-File token) for the card used in a successful checkout. This token is bound to the Digital Payment Application (DPA) and can be used across multiple merchants within the DPA ecosystem. The enrollmentReferenceData from the checkout response must be used within 24 hours.
Key characteristics:
The following diagram illustrates the complete flow for this use case:
Endpoint: POST /cards
Submits the enrollmentReferenceData from a successful checkout to create a DPA-bound token. The serviceId field must be set to CARD_ON_FILE to indicate this is a DPA token enrollment.
Request:
{
"serviceId": "CARD_ON_FILE",
"enrollmentReferenceData": {
"id": "{{enrollmentReferenceDataId}}",
"type": "{{enrollmentReferenceDataType}}"
}
}
Response:
{
"srcDigitalCardId": "{{dpaTokenId}}",
"maskedCard": {
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "{{descriptorName}}"
}
}
}
Implementation Notes:
Once the DPA token is created, it can be used for streamlined checkout flows:
DPA Token (CARD_ON_FILE):
SRCi Token (PARTNER_TOKEN):
A consumer completes checkout using a previously enrolled SRCi or DPA token, enabling streamlined transactions without full identity validation.
Classification: Optional
This use case covers the streamlined checkout flow where a consumer uses a previously enrolled token (SRCi token from UC8 or DPA token from UC9) to complete a transaction. The token eliminates the need for full identity validation, providing a faster checkout experience. Depending on Visa's risk assessment, step-up authentication may or may not be required.
Key characteristics:
The following diagram illustrates the complete flow for this use case:
Endpoint: POST /transaction/credentials
If Visa's risk engine approves, checkout proceeds without step-up and the encrypted payment payload is returned directly.
Request:
{
"srcDigitalCardId": "{{tokenId}}",
"srcDpaId": "{{srcDpaId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
}
}
}
Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"maskedCard": {
"srcDigitalCardId": "{{tokenId}}",
"panLastFour": "{{panLastFour}}"
},
"assuranceData": { "eci": "07" },
"encryptedPayload": "{{encryptedPayload}}"
}
}
Implementation notes:
Endpoint: POST /transaction/credentials (twice)
If Visa's risk engine requires step-up, the first checkout call returns uriData. The consumer completes the Visa-hosted authentication challenge, then a second checkout call with assuranceData retrieves the payload.
First Request:
{
"srcDigitalCardId": "{{tokenId}}",
"srcDpaId": "{{srcDpaId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
}
}
}
First Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"pendingEvents": ["PENDING_CARDHOLDER_AUTHENTICATION"],
"uriData": {
"uri": "{{visaHostedStepUpUrl}}",
"method": "GET"
}
}
}
Client-Side: Launch the Visa-hosted step-up UI using the uri. Listen for window.postMessage containing assuranceData.
Second Request (after step-up):
{
"srcDigitalCardId": "{{tokenId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"assuranceData": "{{assuranceDataFromPostMessage}}",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
}
}
}
Second Response:
{
"checkoutResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"maskedCard": {
"srcDigitalCardId": "{{tokenId}}",
"panLastFour": "{{panLastFour}}"
},
"assuranceData": { "eci": "05" },
"encryptedPayload": "{{encryptedPayload}}"
}
}
Implementation notes:
Endpoint: GET /transaction/credentials
Only required when payloadTypeIndicatorCheckout = SUMMARY in the Step 1 response.
Request:
GET /transaction/credentials
?srcCorrelationId={{srcCorrelationId}}
Implementation Notes:
Endpoint: POST /confirmations
After the transaction completes — regardless of outcome — notify Visa of the result. Required for every transaction.
Request:
{
"srcCorrelationId": "{{srcCorrelationId}}",
"confirmationData2": {
"checkoutEventType": "01",
"confirmationStatus": "01",
"confirmationTimestamp": "{{unixTimestamp}}"
}
}
Implementation notes:
Best practices for token usage:
A consumer enrolls a card into Visa Click to Pay with CVV2 verification, creating a verified card that may not require step-up authentication at checkout.
Classification: Mandatory
This use case covers the card enrollment flow where a consumer provides CVV2 during enrollment. Providing CVV2 verifies the card at enrollment time, which may eliminate the need for step-up authentication during subsequent checkouts. This is the recommended enrollment method for the best consumer experience. After enrollment, the consumer can proceed with checkout following any of the standard checkout use cases (UC1-UC5) depending on their identity validation method.
Key characteristics:
The following diagram illustrates the complete flow for this use case:
Endpoint: POST /cards
Enrolls the card into Visa Click to Pay with CVV2 verification. The card is enrolled as verified, which may eliminate step-up requirements at checkout.
Request:
{
"cardData": {
"accountNumber": "{{pan}}",
"expirationDate": {
"month": "{{mm}}",
"year": "{{yyyy}}"
},
"cardSecurityCode": "{{cvv2}}"
},
"consumerIdentity": {
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"identityValue": "{{emailOrPhone}}"
}
}
Response:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"maskedCard": {
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "{{descriptorName}}",
"artUri": "{{cardArtUri}}"
}
}
}
Implementation Notes:
After successful enrollment with CVV2, the card can be used in checkout flows. The specific checkout flow depends on the identity validation method:
Because the card was enrolled with CVV2, it is verified and less likely to require step-up authentication at checkout (subject to Visa's risk assessment).
Advantages of enrolling with CVV2:
A consumer enrolls a card into Visa Click to Pay without CVV2 verification, creating an unverified card that will require step-up authentication at first checkout.
Classification: Optional
This use case covers the card enrollment flow where a consumer does not provide CVV2 during enrollment. Without CVV2 verification, the card is enrolled as unverified and will require step-up authentication (3DS or CVV2 challenge) at the first checkout. This enrollment method may be used when CVV2 is not available or when the consumer prefers to defer verification until checkout. After enrollment, the consumer must complete step-up authentication during their first checkout (UC2 or UC3).
Key characteristics:
The following diagram illustrates the complete flow for this use case:
Endpoint: POST /cards
Enrolls the card into Visa Click to Pay without CVV2 verification. The card is enrolled as unverified and will require step-up authentication at first checkout.
Request:
{
"cardData": {
"accountNumber": "{{pan}}",
"expirationDate": {
"month": "{{mm}}",
"year": "{{yyyy}}"
}
},
"consumerIdentity": {
"identityType": "{{EMAIL_ADDRESS or MOBILE_PHONE_NUMBER}}",
"identityValue": "{{emailOrPhone}}"
}
}
Response:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"maskedCard": {
"panLastFour": "{{panLastFour}}",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "{{descriptorName}}",
"artUri": "{{cardArtUri}}"
}
},
"pendingEvents": ["PENDING_CARDHOLDER_AUTHENTICATION"]
}
Implementation Notes:
After enrollment without CVV2, the card will require step-up authentication at the first checkout. The specific checkout flow depends on the step-up method:
The step-up authentication verifies the card and consumer authorization. After successful step-up at the first checkout, subsequent checkouts may not require step-up (subject to Visa's risk assessment).
Scenarios where enrollment without CVV2 may be appropriate:
Trade-offs:
Without CVV2 (UC12):
With CVV2 (UC11):