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 |
|---|---|---|---|
| UC01 | 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 |
| UC02 | 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 |
| UC03 | 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 |
| UC04 | Returning consumer — Federated identity, 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 |
| UC05 | Returning consumer — Federated identity, step-up required | A recognized consumer using federated identity is asked to complete a step-up challenge before checkout proceeds. | Optional |
| UC06 | Returning consumer — Add a new card during checkout | 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 |
| UC07 | 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 |
| UC08 | SRCi token request 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 |
| UC09 | DPA token request 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 | Checkout using tokens | 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 |
| UC13 | Returning consumer — Visa identity verification, Passkey step-up | A recognized consumer is asked to complete a Passkey authentication challenge before checkout can proceed. Required when the SRCi supports pre-init and the consumer has a registered Visa Payment Passkey. | Conditional |
| UC14 | Returning consumer — Visa identity verification, issuer OTP step-up | A recognized consumer is asked to enter a one-time password delivered by their card issuer before checkout can proceed. Required when the card issuer supports Cloud Token Framework OTP authentication. | Conditional |
| UC15 | Returning consumer — Visa identity verification, issuer online banking step-up | A recognized consumer is asked to approve the transaction in their issuer's banking app or web portal before checkout can proceed. Required when the card issuer supports Cloud Token Framework app-based authentication. | 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:
{
"srcClientId": "{{srcClientId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"srcDigitalCardId": "{{srcDigitalCardId}}",
"dpaData": {
"dpaUri": "{{dpaUri}}"
},
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
},
"authenticationPreferences": {
"payloadRequested": "AUTHENTICATED"
},
"acquirerMerchantId": "{{acquirerMerchantId}}",
"acquirerBin": "{{acquirerBin}}",
"merchantName": "{{merchantName}}",
"consumerNationalIdentifierRequested": true,
"dpaLocale": "en_US"
},
"payloadTypeIndicatorCheckout": "FULL"
}
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": [
{
"verificationType": "CARDHOLDER",
"verificationEntity": "03",
"verificationEvents": [
"01"
],
"verificationMethod": "01",
"verificationResults": "01",
"verificationTimestamp": "1754500546",
"methodResults": {
"threeDsData": {
"transStatus": "Y",
"dsTransId": " {{dsTransId}}",
"acsTransId": "{{acsTransId}}"
}
}
}
],
"eci": "05"
},
"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": "07" },
"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:
{
"srcClientId": "{{srcClientId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"srcDigitalCardId": "{{srcDigitalCardId}}",
"dpaData": {
"dpaUri": "{{dpaUri}}"
},
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
},
"authenticationPreferences": {
"payloadRequested": "AUTHENTICATED"
},
"acquirerMerchantId": "{{acquirerMerchantId}}",
"acquirerBin": "{{acquirerBin}}",
"merchantName": "{{merchantName}}",
"consumerNationalIdentifierRequested": true,
"dpaLocale": "en_US"
},
"payloadTypeIndicatorCheckout": "FULL"
}
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}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"assuranceData": {
"verificationData": [
{
"verificationType": "CARD",
"verificationEntity": "02",
"verificationEvents": [
"01"
],
"verificationMethod": "02",
"verificationResults": "01",
"verificationTimestamp": "1754500546"
}
],
"eci": "07"
}
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
},
"authenticationPreferences": { "payloadRequested": "AUTHENTICATED" }
}
}
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:
{
"payloadResponse": {
"srcCorrelationId": "{{srcCorrelationId}}",
"assuranceData": { "eci": "07" },
"encryptedPayload": "{{encryptedPayload}}"
}
}
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:
{
"srcClientId": "{{srcClientId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"srcDigitalCardId": "{{srcDigitalCardId}}",
"dpaData": {
"dpaUri": "{{dpaUri}}"
},
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
},
"authenticationPreferences": {
"payloadRequested": "AUTHENTICATED"
},
"acquirerMerchantId": "{{acquirerMerchantId}}",
"acquirerBin": "{{acquirerBin}}",
"merchantName": "{{merchantName}}",
"consumerNationalIdentifierRequested": true,
"dpaLocale": "en_US"
},
"payloadTypeIndicatorCheckout": "FULL"
}
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": "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 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):
A returning consumer completes checkout with Visa Payment Passkey step-up authentication after card selection. Required when the SRCi supports pre-init.
Classification: Conditional
This use case covers the returning consumer checkout flow where Visa's risk engine determines that Visa Payment Passkey (FIDO2) 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 for the Passkey challenge. The SRCi launches this URI in a popup, the consumer completes Passkey authentication, and the SRCi re-submits checkout with the returned assuranceData. The authenticated payload includes ECI 05.
Key characteristics:
Steps 1–3 are identical to UC1. Refer to UC1 for full request/response details covering:
Endpoint: POST /transaction/credentials
SRCi submits checkout with payloadRequested: AUTHENTICATED. Visa's risk engine determines Passkey step-up is required and returns a response without an encrypted payload — instead returning uriData to launch the hosted Passkey step-up UI.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
},
"authenticationPreferences": {
"payloadRequested": "AUTHENTICATED"
},
"acquirerMerchantId": "{{acquirerMerchantId}}",
"acquirerBin": "{{acquirerBin}}",
"merchantName": "{{merchantName}}",
"merchantCategoryCode": "{{merchantCategoryCode}}"
}
}
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 Visa Payment Passkey (FIDO2) authentication 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 Passkey authentication result and releases the authenticated payment payload with ECI 05.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"assuranceData": {
"verificationData": [
{
"verificationType": "CARDHOLDER",
"verificationEntity": "02",
"verificationEvents": [
"01"
],
"verificationMethod": "07",
"verificationResults": "01",
"verificationTimestamp": "1754500546"
}
],
"eci": "05"
}
"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": "07"
},
"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 returning consumer completes checkout with issuer OTP step-up authentication via Cloud Token Framework after card selection. Applies when the issuer supports Cloud Token Framework OTP authentication.
Classification: Conditional
This use case covers the returning consumer checkout flow where Visa's risk engine determines that Issuer OTP step-up authentication is required before the payment payload is released. The card's issuer verifies the cardholder by sending a one-time password (typically a 6-digit code) to the cardholder's registered email or mobile on file with the issuer. Visa coordinates OTP delivery and verification with the issuer through the Cloud Token Framework (CTF) — leveraging token-to-device binding to ensure the OTP is delivered to the legitimate cardholder. Steps 1–3 cover identity lookup, OTP validation, and profile retrieval — identical to UC1 and UC2. At checkout, Visa returns a hosted authentication URI rather than a payload. The SRCi launches this URI, the consumer enters the issuer-supplied OTP in the Visa-hosted experience, and the SRCi re-submits checkout with the returned assuranceData. The authenticated payload includes ECI 05.
Key characteristics:
Steps 1–3 are identical to UC1. Refer to UC1 for full request/response details covering:
Endpoint: POST /transaction/credentials
SRCi submits checkout with payloadRequested: AUTHENTICATED. When Visa selects Issuer OTP via CTF as the step-up method (based on issuer support, card country/region, and risk evaluation), the response carries authenticationMethodType: "SRCS_HOSTED_AUTHENTICATION" with uriData — identical to the 3DS and Passkey response shape. The SRCi does not need to choose the method; Visa coordinates with the issuer and administers the OTP challenge inside the hosted experience.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
},
"authenticationPreferences": {
"payloadRequested": "AUTHENTICATED"
},
"acquirerMerchantId": "{{acquirerMerchantId}}",
"acquirerBin": "{{acquirerBin}}",
"merchantName": "{{merchantName}}",
"merchantCategoryCode": "{{merchantCategoryCode}}"
}
}
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. Visa coordinates with the issuer through CTF: the issuer (or Visa on the issuer's behalf) delivers a one-time password to the cardholder's registered email or mobile. The consumer enters the OTP in the Visa-hosted UI; Visa validates the code with the issuer via CTF. Visa returns assuranceData via postMessage on completion.
Implementation notes:
Endpoint: POST /transaction/credentials
Re-submits checkout with assuranceData from Step 5. Visa validates the issuer OTP result and releases the authenticated payment payload with ECI 05.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"assuranceData": {
"verificationData": [
{
"verificationType": "CARDHOLDER",
"verificationEntity": "03",
"verificationEvents": [
"01"
],
"verificationMethod": "04",
"verificationResults": "01",
"verificationTimestamp": "1754500546"
}
],
"eci": "05"
}
"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": "07"
},
"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 returning consumer completes checkout with issuer app-based authentication via Cloud Token Framework after card selection. Applies when the issuer supports Cloud Token Framework app-based authentication.
Classification: Conditional
This use case covers the returning consumer checkout flow where Visa's risk engine determines that Issuer Online Banking authentication (also known as issuer app authentication) is required before the payment payload is released. The issuer authenticates the cardholder inside its own mobile banking app or secure web portal — typically through a push notification, in-app biometric login, or tap-to-approve confirmation. Visa coordinates with the issuer through the Cloud Token Framework (CTF), leveraging token-to-device binding to ensure the challenge is delivered to the correct cardholder's app on the bound device. Steps 1–3 cover identity lookup, OTP validation, and profile retrieval — identical to UC1 and UC2. At checkout, Visa returns a hosted authentication URI rather than a payload. The SRCi launches this URI; Visa redirects to the issuer's secure flow; the cardholder approves the transaction in their banking app or web portal; the issuer confirms back to Visa via CTF; Visa returns assuranceData. The SRCi re-submits checkout. The authenticated payload includes ECI 05.
Key characteristics:
Steps 1–3 are identical to UC1. Refer to UC1 for full request/response details covering:
Endpoint: POST /transaction/credentials
SRCi submits checkout with payloadRequested: AUTHENTICATED. When Visa selects Issuer Online Banking authentication via CTF as the step-up method (based on issuer support, card country/region, token-to-device binding state, and risk evaluation), the response carries authenticationMethodType: "SRCS_HOSTED_AUTHENTICATION" with uriData — identical to the 3DS, Passkey, and Issuer OTP response shape. The SRCi does not need to choose the method; Visa coordinates the issuer flow inside the hosted experience.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"dpaTransactionOptions": {
"transactionAmount": {
"transactionAmount": "{{transactionAmount}}",
"transactionCurrencyCode": "{{currencyCode}}"
},
"authenticationPreferences": {
"payloadRequested": "AUTHENTICATED"
},
"acquirerMerchantId": "{{acquirerMerchantId}}",
"acquirerBin": "{{acquirerBin}}",
"merchantName": "{{merchantName}}",
"merchantCategoryCode": "{{merchantCategoryCode}}"
}
}
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. Visa initiates the issuer authentication flow through CTF, leveraging token-to-device binding to route the challenge to the correct cardholder. Depending on the issuer's capability and the cardholder's device, the consumer may receive a push notification to their banking app, be redirected to the issuer's secure web portal, or be prompted to confirm in an embedded issuer frame. The cardholder approves the transaction inside the issuer's controlled environment (typically via biometric or PIN inside the banking app). The issuer confirms the authentication result back to Visa via CTF, and Visa returns assuranceData via postMessage on completion.
Implementation notes:
Endpoint: POST /transaction/credentials
Re-submits checkout with assuranceData from Step 5. Visa validates the issuer's authentication result and releases the authenticated payment payload with ECI 05.
Request:
{
"srcDigitalCardId": "{{srcDigitalCardId}}",
"srcDpaId": "{{srcDpaId}}",
"srcCorrelationId": "{{srcCorrelationId}}",
"srciTransactionId": "{{srciTransactionId}}",
"payloadTypeIndicatorCheckout": "FULL",
"assuranceData": {
"verificationData": [
{
"verificationType": "CARDHOLDER",
"verificationEntity": "03",
"verificationEvents": [
"01"
],
"verificationMethod": "02",
"verificationResults": "01",
"verificationTimestamp": "1754500546"
}
],
"eci": "05"
}
"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": "07"
},
"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: