# Visa Click to Pay ## Merchants and Payment Service Providers \\ Start a Project](https://developer.visa.com/portal/#users/new) \\ API Overview](https://developer.visa.com/capabilities/visa-secure-remote-commerce) \\ API Reference](https://developer.visa.com/capabilities/visa-secure-remote-commerce/reference) - [Overview](https://developer.visa.com/capabilities/visa-secure-remote-commerce/docs-getting-started) - [Merchants and PSPs](https://developer.visa.com/capabilities/visa-secure-remote-commerce/docs-merchants-psps) - [Visa Click to Pay API Overview](https://developer.visa.com/capabilities/visa-secure-remote-commerce/ctp-api-overview) - [Getting Started](https://developer.visa.com/capabilities/visa-secure-remote-commerce/getting-started) - [API Fundamentals](https://developer.visa.com/capabilities/visa-secure-remote-commerce/api-fundamentals) - [First Steps](https://developer.visa.com/capabilities/visa-secure-remote-commerce/first-steps) - [Introduction to Visa Click to Pay API](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api) - [Use Cases](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases) - [UC1: Returning Consumer — Visa Identity Verification, No Step-Up](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section0) - [UC2: Returning Consumer — Visa Identity Verification, 3DS Step-Up](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section1) - [UC3: Returning Consumer — Visa Identity Verification, CVV2 Step-Up](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section2) - [UC4: Returning Consumer — Federated Identity, No Step-Up](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section3) - [UC5: Returning Consumer — Federated Identity, Step-Up Required](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section4) - [UC6: Returning Consumer — Add New Card During Checkout](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section5) - [UC7: New Consumer — Enrollment During Checkout](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section6) - [UC8: SRCi Token Request After Checkout](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section7) - [UC9: DPA Token Request After Checkout](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section8) - [UC10: Checkout Using Tokens](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section9) - [UC11: Card Enrollment with CVV2](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section10) - [UC12: Card Enrollment without CVV2](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section11) - [UC13: Returning Consumer — Visa Identity Verification, Passkey Step-Up](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section12) - [UC14: Returning Consumer — Visa Identity Verification, Issuer OTP Step-Up](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section13) - [UC15: Returning Consumer — Visa Identity Verification, Issuer Online Banking Step-Up](https://developer.visa.com/capabilities/visa-secure-remote-commerce/use-cases#section14) - [API Reference](https://developer.visa.com/capabilities/visa-secure-remote-commerce/reference) - [Tutorials and Guides](https://developer.visa.com/capabilities/visa-secure-remote-commerce/tutorials-guides) - [Error Codes and Troubleshooting](https://developer.visa.com/capabilities/visa-secure-remote-commerce/error-codes-and-troubleshooting) - [Terms of Service and Privacy Notice](https://developer.visa.com/capabilities/visa-secure-remote-commerce/terms-privacy) - [Product Terms](https://developer.visa.com/capabilities/visa-secure-remote-commerce/product-terms) - [Glossary](https://developer.visa.com/capabilities/visa-secure-remote-commerce/glossary) Navigate to... _keyboard\_arrow\_down_ ## Use Cases 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 | ### 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. Classification: **Mandatory** ## Overview 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:** - Consumer already has a Visa Click to Pay profile - Identity validation performed by Visa (OTP delivered to registered channel) - No step-up authentication triggered — Visa's risk engine approves without challenge - Checkout payload returned inline (FULL) or via a separate retrieve call (SUMMARY) ## Prerequisites - SRCi is onboarded with valid API credentials - Consumer has an existing Visa Click to Pay profile - Consumer has at least one eligible enrolled card - [Initialize SRC](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api#section0) has been invoked on the checkout page in advance of this flow, and the initializationSessionId from the SRC\_INIT\_COMPLETED response has been captured. ## High-Level Flow The following diagram illustrates the complete flow for this use case: Zoom](https://developer.visa.com/images2/products/visa-click-to-pay/uc1-returning-consumer-visa-no-stepup.png) ## Step 1: Check Consumer Presence **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - If consumerPresent1: false, no idLookupSessionId is returned — redirect to enrollment (UC7) - Store idLookupSessionId — required for Step 2a; it has a limited TTL - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference on VDP. ## Step 2a: Initiate Identity Validation **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - Store idValidationSessionId and validationChannelId - Display maskedValidationChannel so the consumer knows where to expect the OTP - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 2b: Complete Identity Validation **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - The idToken is a Visa-signed JWT — pass it as-is to Step 3; do not modify or cache it across sessions - validationData is a plain string (the OTP value) — not a nested object - On INCORRECT\_OTP: the session remains active — allow the consumer to retry - On EXPIRED\_OTP: call Step 2a again to issue a new OTP - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 3: Retrieve SRC Profile **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - Store srcCorrelationId — required in all subsequent calls within this transaction - Sort the card list by dateOfCardLastUsed descending - Only display cards where digitalCardData.status = ACTIVE - If pendingEvents contains PENDING\_CARDHOLDER\_AUTHENTICATION, that card will trigger step-up at checkout - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 4: Perform Checkout **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - initializationSessionId — obtained from Initialize SRC; required for device profiling and VPPS authentication. See [Initialize SRC](https://developer.visa.com/capabilities/ctpapi/c_initialize_src.dita#c_initialize_src) - ECI 07 — non-authenticated, risk-based approval - If the response contains uriData instead of encryptedPayload, step-up has been triggered — handle via UC2 (3DS) or UC3 (CVV2) - If enrollmentReferenceData is present, store it securely — required for post-checkout token enrollment (UC8/UC9); expires after 24 hours - Decrypt encryptedPayload using the Payload Encryption key pair provisioned during onboarding - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 5: Retrieve Payload (Conditional) **Endpoint:** GET /transaction/credentials Only required when payloadTypeIndicatorCheckout = SUMMARY in the Step 4 response. Retrieves the full encrypted payment payload. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - Only call this endpoint if payloadTypeIndicatorCheckout = SUMMARY was used in Step 4 - This endpoint can only be called once per transaction — the payload is consumed on retrieval - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference . ## Step 6: Transaction Confirmation **Endpoint:** POST /confirmations After the transaction completes — regardless of outcome — notify Visa of the result. Required for every transaction. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - checkoutEventType: 01 = Authorize, 07 = Cancel before Auth — use the appropriate value for your transaction outcome - confirmationStatus: 01 = Success, 02 = Failure confirmationTimestamp: UTC time in Unix epoch format (seconds) - When checkoutEventType = 01 and confirmationStatus = 01, also include networkAuthorizationCode and transactionAmount - Send after every transaction regardless of outcome - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ### 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. Classification: **Mandatory** ## Overview 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:** - Steps 1–3 identical to UC1 — refer to [UC1](https://developer.visa.com/capabilities/visa-secure-remote-commerce/c_uc1_returning_consumer_visa_no_stepup.dita) for full request/response details - Checkout initially returns uriData and pendingEvents: \["PENDING\_CARDHOLDER\_AUTHENTICATION"\] - Visa hosts the 3DS step-up UI — SRCi launches it via popup or iframe - assuranceData returned via window.postMessage after consumer completes authentication - Checkout re-submitted with assuranceData to retrieve the authenticated payload - assuranceData.eci = "05" — fully 3DS-authenticated transaction ## Prerequisites - SRCi is onboarded with valid API credentials - Consumer has an existing Visa Click to Pay profile - SRCi is able to open a popup or embed an iframe for the Visa step-up UI - [Initialize SRC](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api#section0) has been invoked on the checkout page in advance of this flow, and the initializationSessionId from the SRC\_INIT\_COMPLETED response has been captured. ## High-Level Flow The following diagram illustrates the complete flow for this use case: Zoom](https://developer.visa.com/images2/products/visa-click-to-pay/uc2-returning-consumer-visa-3ds-stepup.png) ## Step 1: Check Consumer Presence **Endpoint:** POST /identities/lookup **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** ## Step 2a: Initiate Identity Validation **Endpoint:** POST /identities/validation/initiate **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** ## Step 2b: Complete Identity Validation **Endpoint:** POST /identities/validation/complete **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** ## Step 3: Retrieve SRC Profile **Endpoint:** POST /profiles/prepare **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** ## Step 4: Initiate Checkout (Step-Up Required) **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - initializationSessionId — obtained from Initialize SRC; required for device profiling and VPPS authentication. See [Initialize SRC](https://developer.visa.com/capabilities/ctpapi/c_initialize_src.dita#c_initialize_src) - The absence of encryptedPayload is the expected signal for step-up — not an error - Extract uriData.uri from authenticationMethods\[0\] and launch it in a popup or iframe - Retain srciTransactionId and srcCorrelationId — must match exactly in Step 6 - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 5: Visa-Hosted 3DS Authentication **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:** - assuranceData.eci: "05" for 3DS or Visa Payment Passkey, "07" for CVV2 - Pass the full assuranceData object as received when re-submitting checkout - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 6: Complete Checkout with Assurance Data **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - initializationSessionId — obtained from Initialize SRC; required for device profiling and VPPS authentication. See [Initialize SRC](https://developer.visa.com/capabilities/ctpapi/c_initialize_src.dita#c_initialize_src) - srciTransactionId and srcCorrelationId must be identical to Step 4 - ECI 05 confirms fully 3DS-authenticated transaction — pass this ECI to your acquirer - The decrypted payload dynamicData array contains two entries: TAVV (CARD\_APPLICATION\_CRYPTOGRAM\_LONG\_FORM) and CAV2/AAV (CARDHOLDER\_AUTHENTICATION\_CRYPTOGRAM) — both required by the acquirer - If enrollmentReferenceData is present, store it — required for UC8/UC9 post-checkout token enrollment; expires after 24 hours - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 7: Retrieve Payload (Conditional) **Endpoint:** GET /transaction/credentials Only required when payloadTypeIndicatorCheckout = SUMMARY in Step 6. Retrieves the full authenticated payload. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - The decrypted payload contains two dynamicData entries: TAVV and CAV2/AAV — both must be passed to your acquirer - This endpoint can only be called once per transaction - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 8: Transaction Confirmation **Endpoint:** POST /confirmations After the authenticated transaction completes — regardless of outcome — notify Visa of the final status. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - checkoutEventType: 01 = Authorize, 07 = Cancel before Auth - confirmationStatus: 01 = Success, 02 = Failure - confirmationTimestamp: UTC time in Unix epoch format (seconds) - When checkoutEventType = 01 and confirmationStatus = 01, also include networkAuthorizationCode and transactionAmount - Send after every transaction regardless of outcome - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ### 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. Classification: **Mandatory** ## Overview 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:** - Steps 1–3 identical to UC1 — refer to [UC1](https://developer.visa.com/capabilities/visa-secure-remote-commerce/c_uc1_returning_consumer_visa_no_stepup.dita) for full request/response details - Checkout initially returns uriData and pendingEvents: \["PENDING\_CARDHOLDER\_AUTHENTICATION"\] - Visa hosts the CVV2 step-up UI — SRCi launches it via popup or iframe - assuranceData returned via window.postMessage after consumer completes CVV2 challenge - assuranceData.eci = "07" — non-authenticated risk-based transaction (vs "05" for 3DS in UC2) ## Prerequisites - SRCi is onboarded with valid API credentials - Consumer has an existing Visa Click to Pay profile - Visa's risk engine determines CVV2 step-up is required - [Initialize SRC](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api#section0) has been invoked on the checkout page in advance of this flow, and the initializationSessionId from the SRC\_INIT\_COMPLETED response has been captured. ## High-Level Flow The following diagram illustrates the complete flow for this use case: Zoom](https://developer.visa.com/images2/products/visa-click-to-pay/uc3-returning-consumer-visa-cvv2-stepup.png) ## Step 1: Check Consumer Presence **Endpoint:** POST /identities/lookup **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** ## Step 2a: Initiate Identity Validation **Endpoint:** POST /identities/validation/initiate **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** ## Step 2b: Complete Identity Validation **Endpoint:** POST /identities/validation/complete **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** ## Step 3: Retrieve SRC Profile **Endpoint:** POST /profiles/prepare **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** ## Step 4: Initiate Checkout (CVV2 Step-Up Required) **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - pendingEvents: \["PENDING\_CARDHOLDER\_AUTHENTICATION"\] signals CVV2 step-up is required — launch uriData.uri in a popup or iframe - Do not proceed to re-submit checkout until assuranceData is received via window.postMessage - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 5: Visa-Hosted CVV2 Authentication **No API call — UI event handling** **Implementation notes:** ## Step 6: Complete Checkout with Assurance Data **Endpoint:** POST /transaction/credentials Re-submits checkout with assuranceData from Step 5. Visa validates and releases the encrypted payment payload with ECI 07. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response (payloadTypeIndicatorCheckout = FULL):** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - initializationSessionId — obtained from Initialize SRC; required for device profiling and VPPS authentication. See [Initialize SRC](https://developer.visa.com/capabilities/ctpapi/c_initialize_src.dita#c_initialize_src) - assuranceData submitted must match exactly what was received from window.postMessage - ECI 07 confirms CVV2 step-up accepted - enrollmentReferenceData is required for post-checkout token enrollment (UC8/UC9); expires after 24 hours - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 7: Retrieve Payload (Conditional) **Endpoint:** GET /transaction/credentials Only required when payloadTypeIndicatorCheckout = SUMMARY in the Step 6 checkout response. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - Unlike UC2 (3DS), CVV2 step-up returns a single dynamicData entry — TAVV only, no CAV2/AAV - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 8: Transaction Confirmation **Endpoint:** POST /confirmations After authorization, report the transaction outcome to Visa. Required regardless of authorization result. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** ### UC4: Returning Consumer — Federated Identity, No Step-Up 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** ## Overview 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:** - Consumer already has a Visa Click to Pay profile - Identity validation performed by SRCi or third-party IDP (not Visa OTP) - Federated idToken submitted to Visa for profile retrieval - No step-up authentication triggered — Visa's risk engine approves without challenge - Checkout payload returned inline (FULL) or via a separate retrieve call (SUMMARY) ## Prerequisites - SRCi is onboarded with valid API credentials - SRCi has established federated identity relationship with IDP - Consumer has an existing Visa Click to Pay profile - Consumer has at least one eligible enrolled card - Consumer identity has been validated by SRCi/IDP - [Initialize SRC](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api#section0) has been invoked on the checkout page in advance of this flow, and the initializationSessionId from the SRC\_INIT\_COMPLETED response has been captured. ## High-Level Flow The following diagram illustrates the complete flow for this use case: Zoom](https://developer.visa.com/images2/products/visa-click-to-pay/uc4-returning-consumer-federated-no-stepup.png) ## Step 1: Check Consumer Presence **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - If consumerPresent1: false, redirect to enrollment (UC7 or UC11/UC12) - The idLookupSessionId confirms profile existence but is not used in federated flows - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 2: Validate Identity via Federated IDP **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:** - This step occurs outside the Visa API — no Visa OTP is sent - The federated idToken must conform to the format and signing requirements agreed upon during SRCi onboarding - The idToken must include the consumer's verified identity (email or phone) that matches the Visa Click to Pay profile - Consult your Visa integration documentation for federated identity token specifications ## Step 3: Retrieve SRC Profile **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - Store srcCorrelationId — required in all subsequent calls within this transaction - The federated idToken is passed in the idTokens array - Sort the card list by dateOfCardLastUsed descending - Only display cards where digitalCardData.status = ACTIVE - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 4: Perform Checkout **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - initializationSessionId — obtained from Initialize SRC; required for device profiling and VPPS authentication. See [Initialize SRC](https://developer.visa.com/capabilities/ctpapi/c_initialize_src.dita#c_initialize_src) - ECI 07 — non-authenticated, risk-based approval - If the response contains uriData instead of encryptedPayload, step-up has been triggered — handle via UC5 - If enrollmentReferenceData is present, store it securely — required for post-checkout token enrollment (UC8/UC9) - Decrypt encryptedPayload using the Payload Encryption key pair provisioned during onboarding - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 5: Retrieve Payload (Conditional) **Endpoint:** GET /transaction/credentials Only required when payloadTypeIndicatorCheckout = SUMMARY in the Step 4 response. Retrieves the full encrypted payment payload. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - Only call this endpoint if payloadTypeIndicatorCheckout = SUMMARY was used in Step 4 - This endpoint can only be called once per transaction — the payload is consumed on retrieval - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 6: Transaction Confirmation **Endpoint:** POST /confirmations After the transaction completes — regardless of outcome — notify Visa of the result. Required for every transaction. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - checkoutEventType: 01 = Authorize, 07 = Cancel before Auth - confirmationStatus: 01 = Success, 02 = Failure - confirmationTimestamp: UTC time in Unix epoch format (seconds) - When checkoutEventType = 01 and confirmationStatus = 01, also include networkAuthorizationCode and transactionAmount - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ### UC5: Returning Consumer — Federated Identity, Step-Up Required A recognized consumer completes checkout using federated identity validation, but Visa's risk engine requires additional authentication via step-up challenge. Classification: **Optional** ## Overview 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:** - Consumer already has a Visa Click to Pay profile - Identity validation performed by SRCi or third-party IDP (not Visa OTP) - Federated idToken submitted to Visa for profile retrieval - Step-up authentication triggered by Visa's risk engine - Consumer completes challenge via Visa-hosted UI (popup or iframe) - Checkout payload returned after successful step-up ## Prerequisites - SRCi is onboarded with valid API credentials - SRCi has established federated identity relationship with IDP - Consumer has an existing Visa Click to Pay profile - Consumer has at least one eligible enrolled card - Consumer identity has been validated by SRCi/IDP - Visa's risk engine determines step-up is required - [Initialize SRC](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api#section0) has been invoked on the checkout page in advance of this flow, and the initializationSessionId from the SRC\_INIT\_COMPLETED response has been captured. ## High-Level Flow The following diagram illustrates the complete flow for this use case: Zoom](https://developer.visa.com/images2/products/visa-click-to-pay/uc5-returning-consumer-federated-stepup.png) ## Step 1: Check Consumer Presence **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - If consumerPresent1: false, redirect to enrollment (UC7 or UC11/UC12) - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 2: Validate Identity via Federated IDP **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:** - This step occurs outside the Visa API — no Visa OTP is sent - The federated idToken must conform to the format and signing requirements agreed upon during SRCi onboarding - Consult your Visa integration documentation for federated identity token specifications ## Step 3: Retrieve SRC Profile **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - Store srcCorrelationId — required in all subsequent calls within this transaction - If pendingEvents contains PENDING\_CARDHOLDER\_AUTHENTICATION, that card will trigger step-up at checkout - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 4: Initiate Checkout (Step-Up Triggered) **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - The presence of uriData indicates step-up is required - pendingEvents: \[PENDING\_CARDHOLDER\_AUTHENTICATION\] confirms the authentication requirement - Store srcCorrelationId — required for Step 5 - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 4a: Launch Visa-Hosted Step-Up UI **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:** - Open the uri in a popup window or iframe — do not navigate the main page - Listen for window.postMessage events from the Visa-hosted UI - The postMessage will contain assuranceData upon successful authentication - Handle user cancellation or timeout scenarios gracefully - Refer to the Visa Click to Pay Integration Guide for detailed client-side implementation patterns ## Step 5: Complete Checkout with Assurance Data **Endpoint:** POST /transaction/credentials After the consumer completes step-up authentication, submit the assuranceData received via postMessage to retrieve the encrypted payment payload. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - initializationSessionId — obtained from Initialize SRC; required for device profiling and VPPS authentication. See [Initialize SRC](https://developer.visa.com/capabilities/ctpapi/c_initialize_src.dita#c_initialize_src) - ECI 05 — authenticated via 3DS or equivalent step-up - The assuranceData field contains the authentication proof from the Visa-hosted UI - If enrollmentReferenceData is present, store it securely for post-checkout token enrollment (UC8/UC9) - Decrypt encryptedPayload using the Payload Encryption key pair provisioned during onboarding - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 6: Retrieve Payload (Conditional) **Endpoint:** GET /transaction/credentials Only required when payloadTypeIndicatorCheckout = SUMMARY in the Step 5 response. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - Only call this endpoint if payloadTypeIndicatorCheckout = SUMMARY was used in Step 5 - This endpoint can only be called once per transaction - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 7: Transaction Confirmation **Endpoint:** POST /confirmations After the transaction completes — regardless of outcome — notify Visa of the result. Required for every transaction. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - checkoutEventType: 01 = Authorize, 07 = Cancel before Auth - confirmationStatus: 01 = Success, 02 = Failure - When checkoutEventType = 01 and confirmationStatus = 01, also include networkAuthorizationCode and transactionAmount - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ### UC6: Returning Consumer — Add New Card During Checkout A recognized consumer with an existing Visa Click to Pay profile adds a new card during checkout and completes the transaction. Classification: **Mandatory** ## Overview 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:** - Consumer already has a Visa Click to Pay profile - Consumer provides new card details during checkout - New card is enrolled via POST /cards endpoint - Step-up may be required depending on CVV2 provision and risk assessment - Checkout proceeds with the newly enrolled card ## Prerequisites - SRCi is onboarded with valid API credentials - Consumer has an existing Visa Click to Pay profile - Consumer has completed identity validation (UC1 Steps 1-3 or UC4 Steps 1-3) - Consumer provides new card details (PAN, expiry, optional CVV2) - [Initialize SRC](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api#section0) has been invoked on the checkout page in advance of this flow, and the initializationSessionId from the SRC\_INIT\_COMPLETED response has been captured. ## High-Level Flow The following diagram illustrates the complete flow for this use case: Zoom](https://developer.visa.com/images2/products/visa-click-to-pay/uc6-returning-consumer-add-new-card.png) ## Step 1: Check Consumer Presence **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - Store idLookupSessionId — required for Step 2a - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 2a: Initiate Identity Validation **Endpoint:** POST /identities/validation/initiate Submits the idLookupSessionId to trigger Visa sending a One-Time Passcode to the consumer's registered channel. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - Store idValidationSessionId and validationChannelId - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 2b: Complete Identity Validation **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - The idToken is a Visa-signed JWT — pass it as-is to Step 3 - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 3: Retrieve SRC Profile **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - Store srcCorrelationId — required in all subsequent calls within this transaction - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 4: Enroll New Card **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response (with CVV2):** _content\_copy_ CopyCopied to clipboard ```json ``` **Response (without CVV2):** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - If CVV2 is provided, the card is enrolled as verified — step-up may not be required - If CVV2 is not provided, pendingEvents: \[PENDING\_CARDHOLDER\_AUTHENTICATION\] indicates step-up will be required at checkout - Store the srcDigitalCardId — required for checkout in Step 5 - The cardSecurityCode field is optional but recommended to avoid step-up - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 5: Perform Checkout (Path A: No Step-Up) **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - initializationSessionId — obtained from Initialize SRC; required for device profiling and VPPS authentication. See [Initialize SRC](https://developer.visa.com/capabilities/ctpapi/c_initialize_src.dita#c_initialize_src) - ECI 07 — non-authenticated, risk-based approval - Decrypt encryptedPayload using the Payload Encryption key pair - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 5: Perform Checkout (Path B: Step-Up Required) **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **First Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Client-Side:** Launch the Visa-hosted step-up UI using the uri. Listen for window.postMessage containing assuranceData. **Second Request (after step-up):** _content\_copy_ CopyCopied to clipboard ```json ``` **Second Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - ECI 05 — authenticated via 3DS or equivalent step-up - Refer to UC2 or UC3 for detailed step-up implementation guidance - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 6: Retrieve Payload (Conditional) **Endpoint:** GET /transaction/credentials Only required when payloadTypeIndicatorCheckout = SUMMARY in the Step 5 response. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - Only call this endpoint if payloadTypeIndicatorCheckout = SUMMARY was used - This endpoint can only be called once per transaction - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 7: Transaction Confirmation **Endpoint:** POST /confirmations After the transaction completes — regardless of outcome — notify Visa of the result. Required for every transaction. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** ### UC7: New Consumer — Enrollment During Checkout A new consumer without an existing Visa Click to Pay profile enrolls their first card during checkout and completes the transaction. Classification: **Mandatory** ## Overview 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:** - Consumer does not have an existing Visa Click to Pay profile - First card enrollment creates the consumer's profile - Consumer must accept Terms and Conditions - Step-up may be required depending on CVV2 provision and risk assessment - Checkout proceeds immediately after enrollment ## Prerequisites - SRCi is onboarded with valid API credentials - Consumer does not have an existing Visa Click to Pay profile - Consumer provides card details (PAN, expiry, optional CVV2) - Consumer accepts Visa Click to Pay Terms and Conditions - [Initialize SRC](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api#section0) has been invoked on the checkout page in advance of this flow, and the initializationSessionId from the SRC\_INIT\_COMPLETED response has been captured. ## High-Level Flow The following diagram illustrates the complete flow for this use case: Zoom](https://developer.visa.com/images2/products/visa-click-to-pay/uc7-new-consumer-enrollment-during-checkout.png) ## Step 1: Check Consumer Presence **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - consumerPresent1: false indicates no existing profile — proceed to card enrollment - No idLookupSessionId is returned for new consumers - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 2: Enroll First Card (Creates Profile) **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response (with CVV2):** _content\_copy_ CopyCopied to clipboard ```json ``` **Response (without CVV2):** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - This enrollment creates the consumer's Visa Click to Pay profile - Consumer must accept Terms and Conditions before calling this endpoint - If CVV2 is provided, the card is enrolled as verified — step-up may not be required - If CVV2 is not provided, pendingEvents: \[PENDING\_CARDHOLDER\_AUTHENTICATION\] indicates step-up will be required at checkout - Store the srcDigitalCardId — required for checkout in Step 3 - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 3: Perform Checkout (Path A: No Step-Up) **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - initializationSessionId — obtained from Initialize SRC; required for device profiling and VPPS authentication. See [Initialize SRC](https://developer.visa.com/capabilities/ctpapi/c_initialize_src.dita#c_initialize_src) - ECI 07 — non-authenticated, risk-based approval - Note: srcCorrelationId is returned in the checkout response for new enrollments - Decrypt encryptedPayload using the Payload Encryption key pair - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 3: Perform Checkout (Path B: Step-Up Required) **Endpoint:** POST /transaction/credentials (twice) **First Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **First Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Client-Side:** Launch the Visa-hosted step-up UI using the uri. Listen for window.postMessage containing assuranceData. **Second Request (after step-up):** _content\_copy_ CopyCopied to clipboard ```json ``` **Second Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - ECI 05 — authenticated via 3DS or equivalent step-up - Store srcCorrelationId from the first response — required for the second checkout call - Refer to UC2 or UC3 for detailed step-up implementation guidance - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 4: Retrieve Payload (Conditional) **Endpoint:** GET /transaction/credentials Only required when payloadTypeIndicatorCheckout = SUMMARY in the Step 3 response. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** ## Step 5: Transaction Confirmation **Endpoint:** POST /confirmations After the transaction completes — regardless of outcome — notify Visa of the result. Required for every transaction. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** ### UC8: SRCi Token Request After Checkout After a successful checkout, the SRCi requests a partner-bound token for streamlined future transactions within their own ecosystem. Classification: **Optional** ## Overview 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:** - Executed after a successful checkout (UC1-UC7) - Requires enrollmentReferenceData from checkout response - Creates an SRCi-bound token for partner use - Token valid for 24 hours after checkout - Enables streamlined future checkouts (UC10) ## Prerequisites - SRCi is onboarded with valid API credentials - A successful checkout has been completed (UC1-UC7) - enrollmentReferenceData was returned in the checkout response - Token enrollment request made within 24 hours of checkout - [Initialize SRC](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api#section0) has been invoked on the checkout page in advance of this flow, and the initializationSessionId from the SRC\_INIT\_COMPLETED response has been captured. ## High-Level Flow The following diagram illustrates the complete flow for this use case: Zoom](https://developer.visa.com/images2/products/visa-click-to-pay/uc8-srci-token-request-after-checkout.png) ## Step 1: Request SRCi-Bound Token **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - The enrollmentReferenceData object contains id and type fields from the checkout response - serviceId: PARTNER\_TOKEN indicates this is an SRCi-bound token enrollment - The returned srcDigitalCardId is the SRCi token — store it securely for future use - This token is bound to your SRCi and can only be used within your ecosystem - enrollmentReferenceData expires 24 hours after the original checkout - The token can be used in UC10 for streamlined future checkouts - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Token Usage Once the SRCi token is created, it can be used for streamlined checkout flows: - Store the srcDigitalCardId (SRCi token) securely in your system - Associate it with the consumer's account in your ecosystem - Use it in future checkouts via UC10 without requiring full identity validation - The token remains valid until revoked by the consumer or issuer ## Related Use Cases - **UC9:** DPA Token Request After Checkout — for DPA-bound tokens (Card-on-File) - **UC10:** Checkout Using Tokens — for using the SRCi token in future checkouts ### UC9: DPA Token Request After Checkout 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** ## Overview 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:** - Executed after a successful checkout (UC1-UC7) - Requires enrollmentReferenceData from checkout response - Creates a DPA-bound token for Card-on-File use - Token valid for 24 hours after checkout - Enables cross-merchant usage within DPA ecosystem - Enables streamlined future checkouts (UC10) ## Prerequisites ## High-Level Flow The following diagram illustrates the complete flow for this use case: Zoom](https://developer.visa.com/images2/products/visa-click-to-pay/uc9-dpa-token-request-after-checkout.png) ## Step 1: Request DPA-Bound Token **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - The enrollmentReferenceData object contains id and type fields from the checkout response - serviceId: CARD\_ON\_FILE indicates this is a DPA-bound token enrollment - The returned srcDigitalCardId is the DPA token — store it securely for future use - This token is bound to the DPA and can be used across multiple merchants within the DPA ecosystem - enrollmentReferenceData expires 24 hours after the original checkout - The token can be used in UC10 for streamlined future checkouts - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Token Usage Once the DPA token is created, it can be used for streamlined checkout flows: - Store the srcDigitalCardId (DPA token) securely in your system - Associate it with the consumer's account in your ecosystem - Use it in future checkouts via UC10 without requiring full identity validation - The token can be used across multiple merchants within the DPA ecosystem - The token remains valid until revoked by the consumer or issuer ## DPA Token vs. SRCi Token **DPA Token (CARD\_ON\_FILE):** - Bound to the Digital Payment Application - Can be used across multiple merchants within the DPA ecosystem - Suitable for Card-on-File scenarios - Broader scope of usage **SRCi Token (PARTNER\_TOKEN):** - Bound to the specific SRCi - Can only be used within the SRCi's own ecosystem - Suitable for partner-specific scenarios - Narrower scope of usage ## Related Use Cases - **UC8:** SRCi Token Request After Checkout — for SRCi-bound tokens - **UC10:** Checkout Using Tokens — for using the DPA token in future checkouts ### UC10: Checkout Using Tokens A consumer completes checkout using a previously enrolled SRCi or DPA token, enabling streamlined transactions without full identity validation. Classification: **Optional** ## Overview 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:** - Uses pre-enrolled token (SRCi or DPA token) - No identity validation required (token represents verified identity) - Streamlined checkout experience - Step-up may be required based on risk assessment - Suitable for returning consumers with saved payment methods ## Prerequisites - SRCi is onboarded with valid API credentials - Consumer has a previously enrolled token (from UC8 or UC9) - Token is stored securely and associated with consumer's account - Token is still valid (not revoked by consumer or issuer) - [Initialize SRC](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api#section0) has been invoked on the checkout page in advance of this flow, and the initializationSessionId from the SRC\_INIT\_COMPLETED response has been captured. ## High-Level Flow The following diagram illustrates the complete flow for this use case: Zoom](https://developer.visa.com/images2/products/visa-click-to-pay/uc10-checkout-using-tokens.png) ## Step 1: Perform Checkout with Token (Path A: No Step-Up) **Endpoint:** POST /transaction/credentials If Visa's risk engine approves, checkout proceeds without step-up and the encrypted payment payload is returned directly. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - initializationSessionId — obtained from Initialize SRC; required for device profiling and VPPS authentication. See [Initialize SRC](https://developer.visa.com/capabilities/ctpapi/c_initialize_src.dita#c_initialize_src) - The srcDigitalCardId is the token obtained from UC8 (SRCi token) or UC9 (DPA token) - No srcCorrelationId is required in the request — it's returned in the response - ECI 07 — non-authenticated, risk-based approval - Decrypt encryptedPayload using the Payload Encryption key pair - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Step 1: Perform Checkout with Token (Path B: Step-Up Required) **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **First Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Client-Side:** Launch the Visa-hosted step-up UI using the uri. Listen for window.postMessage containing assuranceData. **Second Request (after step-up):** _content\_copy_ CopyCopied to clipboard ```json ``` **Second Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** ## Step 2: Retrieve Payload (Conditional) **Endpoint:** GET /transaction/credentials Only required when payloadTypeIndicatorCheckout = SUMMARY in the Step 1 response. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** ## Step 3: Transaction Confirmation **Endpoint:** POST /confirmations After the transaction completes — regardless of outcome — notify Visa of the result. Required for every transaction. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** ## Token Management **Best practices for token usage:** - Store tokens securely using industry-standard encryption - Associate tokens with consumer accounts in your system - Implement token lifecycle management (creation, usage, revocation) - Handle token expiration and revocation gracefully - Provide consumers with visibility and control over their saved tokens - Monitor token usage for fraud detection ## Related Use Cases - **UC8:** SRCi Token Request After Checkout — for creating SRCi tokens - **UC9:** DPA Token Request After Checkout — for creating DPA tokens ### UC11: Card Enrollment with CVV2 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** ## Overview 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:** - Card enrolled with CVV2 verification - Card status set to ACTIVE and verified - No PENDING\_CARDHOLDER\_AUTHENTICATION flag - May not require step-up at checkout (subject to risk assessment) - Recommended enrollment method for optimal user experience ## Prerequisites - SRCi is onboarded with valid API credentials - Consumer provides card details including CVV2 - Consumer accepts Visa Click to Pay Terms and Conditions (for new profiles) - [Initialize SRC](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api#section0) has been invoked on the checkout page in advance of this flow, and the initializationSessionId from the SRC\_INIT\_COMPLETED response has been captured. ## High-Level Flow The following diagram illustrates the complete flow for this use case: Zoom](https://developer.visa.com/images2/products/visa-click-to-pay/uc11-card-enrollment-with-cvv2.png) ## Step 1: Enroll Card with CVV2 **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - The cardSecurityCode field contains the CVV2 value - Card status is ACTIVE and verified — no pendingEvents returned - Store the srcDigitalCardId — required for future checkouts - If this is the consumer's first card, this enrollment creates their Visa Click to Pay profile - Consumer must accept Terms and Conditions before enrollment (for new profiles) - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Post-Enrollment Checkout After successful enrollment with CVV2, the card can be used in checkout flows. The specific checkout flow depends on the identity validation method: - **UC1:** Returning Consumer — Visa Identity Verification, No Step-Up - **UC2:** Returning Consumer — Visa Identity Verification, 3DS Step-Up - **UC3:** Returning Consumer — Visa Identity Verification, CVV2 Step-Up - **UC4:** Returning Consumer — Federated Identity, No Step-Up - **UC5:** Returning Consumer — Federated Identity, Step-Up Required 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). ## CVV2 Enrollment Benefits **Advantages of enrolling with CVV2:** - Card is verified at enrollment time - Reduces likelihood of step-up authentication at checkout - Provides better consumer experience with fewer friction points - Demonstrates card possession and authorization - Recommended best practice for card enrollment ## Related Use Cases - **UC12:** Card Enrollment without CVV2 — alternative enrollment method - **UC7:** New Consumer Enrollment During Checkout — enrollment during checkout flow - **UC6:** Returning Consumer Add New Card — adding cards to existing profiles ### UC12: Card Enrollment without 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** ## Overview 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:** - Card enrolled without CVV2 verification - Card status set to ACTIVE but unverified - PENDING\_CARDHOLDER\_AUTHENTICATION flag present - Step-up authentication required at first checkout - Alternative enrollment method when CVV2 not available ## Prerequisites - SRCi is onboarded with valid API credentials - Consumer provides card details without CVV2 - Consumer accepts Visa Click to Pay Terms and Conditions (for new profiles) - [Initialize SRC](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api#section0) has been invoked on the checkout page in advance of this flow, and the initializationSessionId from the SRC\_INIT\_COMPLETED response has been captured. ## High-Level Flow The following diagram illustrates the complete flow for this use case: Zoom](https://developer.visa.com/images2/products/visa-click-to-pay/uc12-card-enrollment-without-cvv2.png) ## Step 1: Enroll Card without CVV2 **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - The cardSecurityCode field is omitted from the request - Card status is ACTIVE but unverified - pendingEvents: \[PENDING\_CARDHOLDER\_AUTHENTICATION\] indicates step-up will be required at first checkout - Store the srcDigitalCardId — required for future checkouts - If this is the consumer's first card, this enrollment creates their Visa Click to Pay profile - Consumer must accept Terms and Conditions before enrollment (for new profiles) - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference. ## Post-Enrollment Checkout 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: - **UC2:** Returning Consumer — Visa Identity Verification, 3DS Step-Up - **UC3:** Returning Consumer — Visa Identity Verification, CVV2 Step-Up 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). ## When to Use This Enrollment Method **Scenarios where enrollment without CVV2 may be appropriate:** - CVV2 is not available at enrollment time - Consumer prefers to defer verification until checkout - Enrollment occurs in a context where CVV2 collection is not feasible - Quick enrollment is prioritized over immediate verification **Trade-offs:** - Requires step-up authentication at first checkout (additional friction) - May result in higher abandonment rates at checkout - Consumer must complete additional authentication steps - Not recommended as the primary enrollment method ## Comparison with CVV2 Enrollment **Without CVV2 (UC12):** - Card enrolled as unverified - PENDING\_CARDHOLDER\_AUTHENTICATION flag present - Step-up required at first checkout - Additional friction for consumer **With CVV2 (UC11):** - Card enrolled as verified - No PENDING\_CARDHOLDER\_AUTHENTICATION flag - Step-up may not be required at checkout - Better consumer experience (recommended) ## Related Use Cases - **UC11:** Card Enrollment with CVV2 — recommended enrollment method - **UC2:** Returning Consumer — 3DS Step-Up — first checkout with unverified card - **UC3:** Returning Consumer — CVV2 Step-Up — first checkout with unverified card - **UC7:** New Consumer Enrollment During Checkout — enrollment during checkout flow ### UC13: Returning Consumer — Visa Identity Verification, Passkey Step-Up A returning consumer completes checkout with Visa Payment Passkey step-up authentication after card selection. Required when the SRCi supports pre-init. Classification: **Conditional** #### Overview 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 identical to UC1 — refer to [UC1](https://developer.visa.com/capabilities/visa-secure-remote-commerce/c_uc1_returning_consumer_visa_no_stepup.xml) for full request/response details - Checkout initially returns `uriData` and `pendingEvents: ["PENDING_CARDHOLDER_AUTHENTICATION"]` - Visa hosts the Passkey step-up UI — SRCi launches it via popup (iframes are not supported) - `assuranceData` returned via `window.postMessage` after consumer completes Passkey challenge - Checkout re-submitted with `assuranceData` to retrieve the authenticated payload - `assuranceData.eci = "05"` — fully authenticated transaction via Visa Payment Passkey - Applicable when the SRCi supports pre-init and the consumer has a Passkey registered #### Prerequisites - SRCi is onboarded with valid API credentials and supports pre-init - Consumer has an existing Visa Click to Pay profile - Consumer has a Visa Payment Passkey registered - SRCi is able to open a popup for the Visa step-up UI (iframes are not supported) - [Initialize SRC](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api#section0) has been invoked on the checkout page in advance of this flow, and the initializationSessionId from the SRC\_INIT\_COMPLETED response has been captured. #### Steps 1–3: Identity Validation and Profile Retrieval Steps 1–3 are identical to UC1. Refer to [UC1](https://developer.visa.com/capabilities/click-to-pay-api/use-cases) for full request/response details covering: - Step 1: Check Consumer Presence ( `POST /identities/lookup`) - Step 2a: Initiate Identity Validation ( `POST /identities/validation/initiate`) - Step 2b: Complete Identity Validation ( `POST /identities/validation/complete`) - Step 3: Retrieve SRC Profile ( `POST /profiles/prepare`) #### Step 4: Initiate Checkout (Passkey Step-Up Required) **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - The absence of `encryptedPayload` is the expected signal for step-up — not an error - Extract `uriData.uri` from `authenticationMethods[0]` and launch it in a popup (iframes are not supported) - Retain `srciTransactionId` and `srcCorrelationId` — must match exactly in Step 6 - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference on VDP. #### Step 5: Visa-Hosted Passkey Authentication **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:** - `assuranceData.eci`: `"05"` for Visa Payment Passkey authentication - Pass the full `assuranceData` object as received when re-submitting checkout - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference on VDP. #### Step 6: Complete Checkout with Assurance Data **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - `srciTransactionId` and `srcCorrelationId` must be identical to Step 4 - ECI `05` confirms fully authenticated transaction via Visa Payment Passkey - If `enrollmentReferenceData` is present, store it — required for UC8/UC9 post-checkout token enrollment; expires after 24 hours - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference on VDP. #### Step 7: Retrieve Payload (Conditional) **Endpoint:** `GET /transaction/credentials` Only required when `payloadTypeIndicatorCheckout = SUMMARY` in Step 6. Retrieves the full authenticated payload. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation Notes:** - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference on VDP. #### Step 8: Transaction Confirmation **Endpoint:** `POST /confirmations` After the authenticated transaction completes — regardless of outcome — notify Visa of the final status. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - `checkoutEventType`: `01` = Authorize, `07` = Cancel before Auth - `confirmationStatus`: `01` = Success, `02` = Failure - `confirmationTimestamp`: UTC time in Unix epoch format (seconds) - When `checkoutEventType = 01` and `confirmationStatus = 01`, also include `networkAuthorizationCode` and `transactionAmount` - Send after every transaction regardless of outcome - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference on VDP. ### UC14: Returning Consumer — Visa Identity Verification, Issuer OTP Step-Up 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** #### Overview 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:** - Issuer OTP authentication requires the card's issuer to support CTF-based OTP — selection is determined by Visa's risk engine and issuer capability - Note: this OTP is **issuer-delivered** (verifying the cardholder for the issuer) and is distinct from the Visa identity-validation OTP in Steps 2a/2b (verifying consumer identity for Click to Pay) - Checkout initially returns `uriData` and `pendingEvents: ["PENDING_CARDHOLDER_AUTHENTICATION"]` — no payload yet - Visa hosts the OTP step-up UI — SRCi launches it via popup (iframes are not supported) - The OTP is delivered out-of-band via SMS or email by the issuer (or by Visa on the issuer's behalf) - `assuranceData` returned via `window.postMessage` after consumer completes authentication, identified by `verificationMethod: "04"` #### Prerequisites - SRCi is onboarded with valid API credentials - Consumer has an existing Visa Click to Pay profile - Card issuer supports Cloud Token Framework OTP authentication - Issuer has a registered email or mobile number for the cardholder - SRCi is able to open a popup for the Visa step-up UI (iframes are not supported) - [Initialize SRC](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api#section0) has been invoked on the checkout page in advance of this flow, and the initializationSessionId from the SRC\_INIT\_COMPLETED response has been captured. #### Steps 1–3: Identity Validation and Profile Retrieval Steps 1–3 are identical to UC1. Refer to [UC1](https://developer.visa.com/capabilities/click-to-pay-api/use-cases) for full request/response details covering: #### Step 4: Initiate Checkout (Issuer OTP Step-Up Required) **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - The absence of `encryptedPayload` is the expected signal for step-up — not an error - The response shape for Issuer OTP is identical to UC2 (3DS) and UC13 (Passkey) — the SRCi cannot determine the specific method from the response; Visa controls the experience inside the hosted page - Extract `uriData.uri` from `authenticationMethods[0]` and launch it in a popup (iframes are not supported) - Retain `srciTransactionId` and `srcCorrelationId` — must match exactly in Step 6 - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference on VDP. #### Step 5: Visa-Hosted Issuer OTP Authentication **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:** - `verificationMethod: "04"` identifies issuer OTP verification — distinguishing it from 3DS ( `"01"`), Passkey ( `"07"`), and CVV2 ( `"02"` with `verificationType: "CARD"`) - `verificationEntity: "03"` indicates the issuer performed the verification - `assuranceData.eci`: `"05"` — fully authenticated transaction with liability shift, equivalent to 3DS - The OTP delivery channel is controlled by the issuer — typically the email or mobile registered with the issuer for the card, not the Click to Pay profile identity - Pass the full `assuranceData` object as received when re-submitting checkout — do not modify - Validate `event.origin` before consuming the postMessage payload - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference on VDP. #### Step 6: Complete Checkout with Assurance Data **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - `srciTransactionId` and `srcCorrelationId` must be identical to Step 4 - ECI `05` confirms a fully authenticated transaction — pass this ECI to your acquirer - If `enrollmentReferenceData` is present, store it — required for UC8/UC9 post-checkout token enrollment; expires after 24 hours - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference on VDP. #### Step 7: Retrieve Payload (Conditional) **Endpoint:** `GET /transaction/credentials` Only required when `payloadTypeIndicatorCheckout = SUMMARY` in Step 6. Retrieves the full authenticated payload. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference on VDP. #### Step 8: Transaction Confirmation **Endpoint:** `POST /confirmations` After the authenticated transaction completes — regardless of outcome — notify Visa of the final status. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** ### UC15: Returning Consumer — Visa Identity Verification, Issuer Online Banking Step-Up 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** #### Overview 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:** - Issuer Online Banking authentication requires the card's issuer to support CTF app-based authentication — selection is determined by Visa's risk engine and issuer capability - Authentication happens in the issuer's controlled environment (banking app or web portal) — not in a Visa-rendered form - Often delivered as a push notification to the cardholder's mobile banking app on the device bound via CTF, with biometric or PIN approval inside the app - May fall back to a web-based issuer flow if the banking app is not installed - Checkout initially returns `uriData` and `pendingEvents: ["PENDING_CARDHOLDER_AUTHENTICATION"]` — no payload yet - Visa hosts the entry-point step-up UI — SRCi launches it via popup (iframes are not supported) - `assuranceData` returned via `window.postMessage` after the issuer confirms approval, identified by `verificationMethod: "02"` with `verificationEntity: "03"` #### Prerequisites - SRCi is onboarded with valid API credentials - Consumer has an existing Visa Click to Pay profile - Card issuer supports Cloud Token Framework app-based / online banking authentication - A token-to-device binding exists for the card and the cardholder's device (or the issuer supports a web-based fallback) - SRCi is able to open a popup for the Visa step-up UI (iframes are not supported) - [Initialize SRC](https://developer.visa.com/capabilities/visa-secure-remote-commerce/introduction-to-visa-click-to-pay-api#section0) has been invoked on the checkout page in advance of this flow, and the initializationSessionId from the SRC\_INIT\_COMPLETED response has been captured. #### Steps 1–3: Identity Validation and Profile Retrieval Steps 1–3 are identical to UC1. Refer to [UC1](https://developer.visa.com/capabilities/click-to-pay-api/use-cases) for full request/response details covering: #### Step 4: Initiate Checkout (Issuer Online Banking Step-Up Required) **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - The absence of `encryptedPayload` is the expected signal for step-up, not an error - The response shape for Issuer Online Banking is identical to UC2 (3DS), UC13 (Passkey), and UC14 (Issuer OTP) — the SRCi cannot determine the specific method from the response; Visa controls the experience inside the hosted page - The hosted UI may launch the issuer's banking app on the cardholder's bound device, or open the issuer's secure web portal — handle popups that may briefly transition through issuer-controlled URLs - Extract `uriData.uri` from `authenticationMethods[0]` and launch it in a popup (iframes are not supported) - Retain `srciTransactionId` and `srcCorrelationId`; must match exactly in Step 6 - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference on VDP. #### Step 5: Visa-Hosted Issuer Online Banking Authentication **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:** - `verificationMethod: "02"` with `verificationEntity: "03"` identifies issuer online banking (app-based) verification — distinguishing it from 3DS ( `"01"`), Passkey ( `"07"`), Issuer OTP ( `"04"`), and CVV2 ( `"02"` with `verificationType: "CARD"`) - Note: the same `verificationMethod` value ( `"02"`) is used for CVV2 — the disambiguator is `verificationType: "CARDHOLDER"` (issuer banking) vs. `"CARD"` (CVV2) - `verificationEntity: "03"` indicates the issuer performed the verification - `assuranceData.eci`: `"05"` — fully authenticated transaction with liability shift, equivalent to 3DS - The user experience may briefly leave the SRCi-launched popup (for example, when the issuer's banking app takes over on mobile) — be prepared for the popup to remain open until Visa posts the result back - Pass the full `assuranceData` object as received when re-submitting checkout — do not modify - Validate `event.origin` before consuming the postMessage payload - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference on VDP. #### Step 6: Complete Checkout with Assurance Data **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:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** #### Step 7: Retrieve Payload (Conditional) **Endpoint:** `GET /transaction/credentials` Only required when `payloadTypeIndicatorCheckout = SUMMARY` in Step 6. Retrieves the full authenticated payload. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Response:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** - For complete field definitions, required vs. optional parameters, and error codes, refer to the Visa Click to Pay API Reference on VDP. #### Step 8: Transaction Confirmation **Endpoint:** `POST /confirmations` After the authenticated transaction completes — regardless of outcome — notify Visa of the final status. **Request:** _content\_copy_ CopyCopied to clipboard ```json ``` **Implementation notes:** _arrow\_upward_ Back to top