Visa Click to Pay

Merchants and Payment Service Providers

Introduction to Visa Click to Pay API

This section covers how to use the Visa Click to Pay API endpoints.

In the Use Cases section, we’ll show you what you can do with them.

Card Enrollment

The Card Enrollment capability allows an SRC Initiator (SRCi) to enroll a consumer payment credential into the Visa Click to Pay ecosystem. Using the POST/cards, an SRCi can either create a new Visa Click to Pay consumer profile with an initial payment credential or add an additional payment credential to an existing consumer profile.

Both Payment SRCis and Non‑Payment SRCis may invoke the Card Enrollment capability. The SRCi is responsible for collecting consumer information, validating the consumer identity, and presenting the Visa Terms of Service and Privacy Notice prior to initiating enrollment. The SRCi must obtain the consumer’s explicit consent to the Visa Terms of Service and Privacy Notice before sending any enrollment data to Visa Click to Pay.

Consumer identity for card enrollment consists of a consumer email address and a mobile phone number. The SRCi must validate the consumer’s identity using these identifiers prior to calling the Card Enrollment endpoint. Visa Click to Pay does not perform consumer identity validation as part of card enrollment.

Once identity validation and consent collection are complete, the SRCi submits the enrollment request to Visa Click to Pay. Visa Click to Pay determines whether a consumer profile already exists and handles profile creation, card association, and card verification status.

Card verification status established during enrollment directly impacts the consumer’s first checkout experience. Providing CVV2 at enrollment may enable frictionless checkout on first use, while omitting CVV2 may require step‑up authentication during the initial transaction.

Key Requirements:

  • consumerIdentity is required with consumer email address or mobile number
    • if the identityType is EMAIL_ADDRESS, a consumer mobileNumber must also be provided
    • if the identityType is MOBILE_PHONE_NUMBER, a consumer emailAddress must also be provided
    • See Consumer object in the API Reference for details of the consumer and consumerIdentity schemas
  • Name, country, and language (for new consumers)

Enrollment will not proceed if the same card is already associated with one of the provided identities.

Workflow:

1. Cardholder provides consumer and card data

The Cardholder provides consumer information and card details to the SRC Initiator (SRCi).

2. SRCi presents Visa Terms of Service and Privacy Notice

The SRCi presents the Visa Terms of Service and Privacy Notice to the Cardholder.

3. Cardholder provides consent

The Cardholder reviews and accepts the Visa Terms of Service and Privacy Notice.

4. SRCi enrolls the card

The SRCi calls the Card Enrollment endpoint (POST /cards) with consumer data, card data, and captured consent.

5. Visa Click to Pay checks whether a consumer profile exists

Visa Click to Pay determines whether a Visa Click to Pay profile already exists for the consumer.

6. Card is added to an existing profile

If a Visa Click to Pay profile exists, the card is added to the existing profile.

7. Consumer profile is created

If a Visa Click to Pay profile does not exist, Visa Click to Pay creates a new consumer profile.

8. Card is added to the new profile

The card is added to the newly created consumer profile.

9. Card verification status is set to VERIFIED

If CVV2 is provided, Visa Click to Pay sets the card verification status to VERIFIED, enabling frictionless checkout on first use.

10. Card verification status is set to UNVERIFIED

If CVV2 is not provided, Visa Click to Pay sets the card verification status to UNVERIFIED, requiring step‑up authentication at first use.

11. Enrollment response is returned

  • If enrollment is successful, Visa Click to Pay returns a 200 OK response with srcDigitalCardId, masked card details, and a correlation identifier.
  • If enrollment fails, a 4xx or 5xx error response is returned with an error code and description.

12. SRCi displays the enrollment result

The SRCi displays the enrollment result (success or failure) to the cardholder.

Card Enrollment API Details

Endpoint Details

Endpoint Name: Enroll Card

Method: POST

Endpoint: /cards

Refer to the API specifications for the complete request and response and any additional details.

Sample Consumer Object

// Unencrypted consumer data object
{
  "firstName": "<first name>",
  "lastName": "<last name>",
  "fullName": "<full name>",
  "consumerIdentity": { // Required
    "identityType": "EMAIL_ADDRESS", // Required
    "identityValue": "<[email protected]>", // Required
    "identityProvider": "SRC"
  },
  "emailAddress": "<[email protected]>",
  "mobileNumber": {
    "countryCode": "1",
    "phoneNumber": "50012345678"
  },
  "nationalIdentifier": "<national identifier>",
  "countryCode": "US", // Required
  "languageCode": "EN" // Required
}
		

Sample Request

{
    "srcClientId": "<Partner SRC Client ID>",
    "encryptedConsumer": "<JWE consumer data>",
    "encryptedCard": "<JWE card data with CVV2>",
    "complianceSettings": {
        "complianceResources": [
            {
                "complianceType": "TERMSANDCONDITIONS",
                "uri": "<Visa T&C URI>"
            },
            {
                "complianceType": "PRIVACY\_POLICY",
                "uri": "<Visa Privacy URI>"
            }
        ]
    }
}
		

Sample Response

{
    "srcCorrelationId": "<ID>",
    "maskedCard": {
        "panBin": "409758",
        "panLastFour": "4340"
    },
    "recognitionToken": "<JWT token>"
}
		

Identity Lookup

Identity Lookup enables SRCis to determine whether the provided consumer identity (email address or mobile phone number) exists within Visa Click to Pay. SRCis (Non-Payment SRCi or Payment SRCi) or an SRCi Enabler may use Identity Lookup.

Workflow:

1. Consumer enters identity

The consumer enters an identity (email address or mobile phone number) and provides it to the SRC Initiator (SRCi).

2. SRCi sends Identity Lookup request

The SRCi calls the Identity Lookup endpoint (POST /identities/lookup) using the provided consumerIdentity and srcClientId.

3. Visa Click to Pay searches for the identity

Visa Click to Pay searches for the provided consumerIdentity in the Visa Click to Pay system.

4. Visa Click to Pay returns lookup result

  • If the identity is recognized, the response includes "consumerPresent1": true and may include consumerStatus, lastUsedCardTimestamp, and idLookupSessionId (when applicable).
  • If the identity is not recognized, the response indicates "consumerPresent1": false.

5. SRCi processes the response

The SRCi uses the lookup result to determine next steps, such as whether to proceed with enrollment or continue with another Visa Click to Pay flow.

6. SRCi displays the result to the consumer

The SRCi displays the lookup outcome to the consumer (recognized or not recognized, and any applicable status).

This information enables SRCis to determine next steps, such as whether to proceed with enrollment, retrieve cards associated with the identity, or initiate any other Visa Click to Pay flows.

Identity Lookup API Details

Endpoint Details

Endpoint Name: Identity Lookup

Method: POST

Endpoint: /identities/lookup

Refer to the API specifications for the complete request and response and any additional details.

Sample Request

{
    "srcClientId": "partner-client-id",
    "consumerIdentity": {
        "identityType": "EMAILADDRESS", // or "MOBILEPHONE_NUMBER"
        "identityValue": "[email protected]"
    }
}
		

Sample Response

{
    "consumerPresent1": true,
    "consumerStatus": "ACTIVE",
    "lastUsedCardTimestamp": "2025-11-19T21:02:10Z",
    "idLookupSessionId": "b1234567-89ab-cdef-0123-456789abcdef",
    "supportedValidationChannels": [
        {
            "validationChannelId": "email",
            "identityType": "EMAIL_ADDRESS",
            "maskedValidationChannel": "us***@example.com"
        }
    ]
}
		

Identity Validation

With the Identity Validation endpoints, you can initiate validation of a claimed consumer identity (email address or mobile phone number) to determine whether that consumer has access to the identity claimed. An SRCi (Payment SRCi or Non-Payment SRCi) or an SRCi Enabler may perform Identity Validation. Identity Validation must be completed before an SRCi or SRCi Enabler may call the Profile Retrieval endpoints.

With express written approval from Visa, an SRCi or SRCi Enabler may use its own identity validation solution to complete consumer identity validation. In this event, the steps below are not applicable.

Identity validation is a two-step process through which Visa Click to Pay confirms that the consumer has access to the identity they have provided. After successful validation, Visa Click to Pay issues a Federated ID Token (idToken), a digitally-signed JWT that attests that a consumer has been successfully verified by an SRC system. The Federated ID Token contains consumer identities that allow other SRC systems to identity the corresponding SRC profile, has an expiration period of 8 minutes, and may be used across multiple API calls within a session.

There are several ways to obtain a Federated ID Token:

  • From Visa when the SRCi completes the identity validation steps in this section
  • From another SRC system operated by a participating network
  • From a third-party identity provider

If an SRCi is integrated with multiple SRC systems, the SRCi must initiate the identity validation operation with the SRC system that has:

 

  • returned "consumerpresent1": true, AND
  • contains the most recently used card (lastUsedCardTimestamp).

 

If no SRC system responds with lastUsedCardTimestamp, the SRCi must choose the SRC system that responded first.

Initiate Identity Validation (Step 1 of 2)

SRCis initiate identity validation by requesting Visa Click to Pay to send a One-Time Passcode (OTP) to the consumer. The Visa SRC system generates an OTP and delivers it via email and/or SMS.

Prerequisites:

  • Identity Lookup has completed successfully
  • Consumer found in Visa SRC system ("consumerPresent1": true)
  • idLookupSessionId available

Workflow:

  1. Send Request: SRCi calls the Initiate Validation endpoint to request Visa Click to Pay to send a One-Time Passcode (OTP) to the consumer's email address or mobile phone number.
  2. System Processing: Visa Click to Pay generates the OTP and delivers it via email and/or SMS.
  3. Response: If successful, the system returns:
    • idValidationSessionID - Session identifier for Step 2
    • validationChannel - Channel used to deliver the OTP (email or SMS)

     

 

Complete Identity Validation (Step 2 of 2)

Verify OTP and Obtain Federated ID Token (idToken).

Prerequisites:

  • Consumer has received OTP via email address and/or mobile phone number
  • Consumer has provided OTP code to SRCi
  • idValidationSessionId available

Workflow:

  1. Send Request: SRCi calls the Complete Identity Validation enrpoint, submitting the consumer's OTP along with the idValidationSessionId from Step 1.
  2. System Processing: Visa Click to Pay validates the OTP and confirms the consumer controls the claimed identity.
  3. Response: If valid, the system returns:

     

    • idToken (Federated ID Token)
    • consumerPresent1 and consumerStatus

     

 

Initiate Identity Validation API Details

Endpoint Details

Endpoint Name: Initiate Identity Validation

Method: POST

Endpoint: /identities/validation/initiate

Refer to the API specifications for the complete request and response and any additional details.

Sample Request

{
    "srcClientId": "partner-client-id",
    "consumerIdentity": {
        "identityType": "EMAIL_ADDRESS",
        "identityValue": "[email protected]"
    }
}
		

Sample Response

{
    "idValidationSessionId": "c2345678-90ab-cdef-1234-567890abcdef",
    "maskedValidationChannel": {
        "validationChannelId": "email",
        "identityType": "EMAIL_ADDRESS",
        "maskedValidationChannel": "us***@example.com"
    }
}
		

Complete Identity Validation API Details

Endpoint Details

Endpoint Name: Complete Identity Validation

Method: POST

Endpoint: /identities/validation/complete

Refer to the API specifications for the complete request and response and any additional details.

Sample Request

{
    "srcClientId": "partner-client-id",
    "idValidationSessionId": "c2345678-90ab-cdef-1234-567890abcdef",
    "validationData": "123456"
}
		

Sample Response

{
    "idToken": "<JWTIDTOKEN>",
    "maskedCard": {
        "srcDigitalCardId": "d48ac10b-58cc-4372-a567-0e02b2c3d489",
        "panBin": "409758",
        "panLastFour": "4340"
    }
}
		

Profile Retrieval

Profile Retrieval enables retrieval of a consumer's Visa Click to Pay profile using the provided consumer identities (email address or mobile phone number) or Federated ID Token(s). The profile contains a list of masked cards and credentials associated with that identity.

Payment SRCis or Non-Payment SRCis may perform Profile Retrieval after the identity is recognized and (where required) validated so a compliant card list can be presented for card selection and proceed to checkout.

Visa supports two forms of identity evidence for Profile Retrieval:

SRCi‑Validated Identity

The SRC Initiator (SRCi) has performed consumer identity verification using its own Visa‑approved methods. In this model, the SRCi may supply consumerIdentities without a Federated ID token and Visa will return profiles accordingly. SRCis must be authorized by Visa to perform identity verification themselves.

Visa‑Validated Identity

Visa performs the consumer identity validation (e.g., OTP) and issues a Federated ID Token. In this model, the SRCi must provide the Visa‑generated ID token in the request. Consumer identity‑only retrieval is not permitted.

If both idTokens[] and consumerIdentities[] are present, the ID token takes precedence.

Workflow:

  1. Send Request: The SRCi sends a POST request to the Profile Retrieval endpoint /profiles/prepare with either:
    • a Federated ID Token (idToken, SRC system generated), or
    • a consumerIdentity (validated identity used only when Visa authorizes the SRCi to perform identity validation themselves)

    A srcCorrelationId may be included to continue an existing session; otherwise, a new one is created.

  2. System Processing: The Visa Click to Pay system validates the SRCi's API credentials. Based on the type of SRCi (if they are permitted with only consumerIdentity or are required to provide the idToken), Visa Click to Pay then uses the provided consumer identity information to look up and prepare the associated Visa Click to Pay profile and masked card details
    • Identity Source Selection: If idToken is present, the SRC system-verified identity is used. SRCi must be authorized to use their own validated identity if no idToken is present. Otherwise, the request is rejected.
    • Profile Retrieval: The system retrieves the consumer's Visa Click to Pay profile to include:

    Only cards for which the consumer has accepted the Visa Terms of Service and Privacy Notice are eligible to be displayed. Cards pending acceptance will not be returned until the cosnumer completes the required acceptance flow.

  3. Response (Consumer Recognized): Visa Click to Pay returns
    • the active srcCorrelationId
    • a profiles[] array containing:
      • maskedConsumer, (primary and alternate identity where applicable)
      • maskedCards[], the filtered and eligible set of cards

    If no cards meet the eligibility criteria (for example, all cards are pending terms acceptance), the reponse contains an empty card list.

 

Profile Retrieval API Details

Endpoint Details

Endpoint Name: Prepare SRC Profile

Method: POST

Endpoint: /profiles/prepare

Refer to the API specifications for the complete request and response and any additional details.

Sample Request

{
    "srcClientId": "partner-client-id",
    "idTokens": [
        "<JWTIDTOKEN>"
    ],
    "consumerIdentities": [
        {
            "identityProvider": "SRC",
            "identityType": "EMAIL_ADDRESS",
            "identityValue": "[email protected]"
        }
    ],
    "srcCorrelationId": "12345678-1234-1234-1234-123456789012",
    "srcDpaId": "DPAID",
    "dpaTransactionOptions": {
        "transactionAmount": {
            "transactionAmount": 99.99,
            "transactionCurrencyCode": "USD"
        },
        "authenticationPreferences": {
            "payloadRequested": "AUTHENTICATED"
        }
    }
}
		


Sample Response

{
    "srcCorrelationId": "12345678-1234-1234-1234-123456789012",
    "profiles": [
        {
            "maskedCards": [
                {
                    "srcDigitalCardId": "card-12345678-abcd-efgh-ijkl-123456789012",
                    "cofEligible": true,
                    "panBin": "411111",
                    "panLastFour": "1111",
                    "tokenBinRange": "444433",
                    "tokenLastFour": "3333",
                    "digitalCardData": {
                        "status": "ACTIVE",
                        "presentationName": "My Visa Card",
                        "authenticationMethods": [
                            {
                                "authenticationMethodType": "CSCVALIDATION",
                                "authenticationSubject": "CARD"
                            },
                            {
                                "authenticationMethodType": "SMSOTP",
                                "authenticationSubject": "CONSUMER",
                                "authenticationCredentialReference": "--1234"
                            }
                        ]
                    }
                }
            ],
            "maskedConsumer": {
                "srcConsumerId": "consumer-98765432-fedc-ba98-7654-321098765432",
                "maskedConsumerIdentity": {
                    "identityProvider": "SRC",
                    "identityType": "EMAILADDRESS",
                    "maskedIdentityValue": "[email protected]"
                },
                "maskedEmailAddress": "[email protected]",
                "maskedMobileNumber": {
                    "countryCode": "1",
                    "phoneNumber": "--1234"
                },
                "countryCode": "US",
                "languageCode": "en",
                "status": "ACTIVE"
            },
            "authorization": "<JWTAUTHORIZATION_TOKEN>",
            "srcDpaId": "dpa-11111111-2222-3333-4444-555555555555"
        }
    ]
}
		

Checkout

Use the POST /transaction/credentials endpoint to initiate and complete a checkout transaction using a consumer‑selected card. Visa Click to Pay performs a transaction risk evaluation and may require additional cardholder authentication before checkout can be finalized.

Both Payment SRCis and Non‑Payment SRCis can invoke the Checkout endpoint. Supported payload types depend on the SRCi classification.

Payload type support

The payloadTypeIndicatorCheckout value determines the type of payload returned in the Checkout API response.

Payment SRCi supported values:

FULL, PAYMENT, NON_PAYMENT, SUMMARY

Non‑Payment SRCi supported values:

NON_PAYMENT, SUMMARY

A Non‑Payment SRCi must not request FULL or PAYMENT payloads.

Additional Authentication

Additional authentication refers to conditional, risk‑based step‑up authentication determined by Visa Click to Pay during checkout initiation. Authentication is not optional for the SRCi. When Visa Click to Pay indicates that authentication is required, the SRCi must support launching and completing the authentication flow.

If authentication is required, Visa Click to Pay returns the authentication method and uriData required to launch the authentication experience. The SRCi must open the uriData URL in a popup window and handle the authentication result returned via postMessage.

Supported Authentication Methods

Visa Click to Pay may require one of the following authentication methods:

  • 3DS (Visa Secure)
  • Visa Payment Passkey (FIDO‑based authentication)
  • CVV2 Challenge

The authentication method is selected by Visa Click to Pay and returned in the Checkout API response. SRCis must not assume or preselect a specific authentication method.

Prerequisites:

Before invoking the Checkout API, the following conditions must be met:

  • The consumer has selected a payment card
  • The SRCi has obtained the srcDigitalCardId
  • The SRCi has obtained the srcCorrelationId

Workflow:

  1. Select card for checkout

    The cardholder selects a card for checkout in the SRCi checkout experience.

  2. Initiate Checkout

    The SRCi calls the Checkout endpoint, including the selected digital card and the desired payloadTypeIndicatorCheckout value.

  3. Risk evaluation

    Visa Click to Pay evaluates transaction risk and determines whether cardholder authentication is required.

  4. Authentication decision

    • If authentication is not required, Visa Click to Pay returns the checkout response with ECI = 07.

    • If authentication is required, Visa Click to Pay returns the authentication method and uriData.

  5. Launch authentication (conditional)

    The SRCi launches the uriData URL in a popup window to initiate the step up authentication experience.

  6. Consumer authentication (conditional)

    The consumer completes the authentication challenge in the Visa hosted user experience using one of the following methods:

    • 3DS (Visa Secure)

    • Visa Payment Passkey (FIDO based)

    • CVV2 Challenge

  7. Authentication result (conditional)

    Visa Click to Pay returns the authentication result via postMessage, including:

    assuranceData

    • ECI = 05, indicating a successfully authenticated transaction

  8. Complete Checkout

    The SRCi resumes checkout by calling the Checkout endpoint again, including the received assuranceData.

  9. Final checkout response

    Visa Click to Pay returns the final checkout response.

  10. Payload decision

    • If payloadTypeIndicatorCheckout is FULL or PAYMENT, the checkout response includes a payload suitable for payment authorization.

    • If payloadTypeIndicatorCheckout is SUMMARY or NON_PAYMENT, a FULL payload is not included in the checkout response.

  11. Payload retrieval (conditional)

    If a FULL payload is required, the SRCi calls the Checkout endpoint with the transaction identifier to retrieve a FULL payload.

  12. Payment authorization

    The SRCi submits the payment authorization request to the payment processor (gateway/acquirer) using the available FULL payload.

    The payment processor returns an authorization result.

  13. Consumer outcome

    a. If authorization is approved, the SRCi displays a payment success confirmation to the cardholder.

    b. If authorization is declined, the SRCi displays a payment failure message and retry options.

 

Checkout API Details

Endpoint Details

Endpoint Name: Checkout Operation

Method: POST

Endpoint: /transaction/credentials

Refer to the API specifications for the complete request and response and any additional details.

Sample Request

{
  "srcDigitalCardId": "cd2cad6f-95d0-4ede-3b16-1664fb8b2b01",
  "srcClientId": "3EY722QTUPZCY5X5A3IY21OLy4te0ZTO9KB3PJMW9ugdQ3ZAQ",
  "srcCorrelationId": "5C8E8754E800R2b3c3ed4-97f1-753d-54a2-1a08d44ad401",
  "srcDpaId": "DPAID",
  "payloadTypeIndicatorCheckout": "FULL",
  "payloadTypeIndicatorPayload": "FULL",
  "encryptedBillingAddress": "eyJraWQiOiJ...OMKug",
  "dpaTransactionOptions": {
    "transactionAmount": {
      "transactionAmount": "14.789",
      "transactionCurrencyCode": "JPY"
    },
    "authenticationPreferences": {
      "payloadRequested": "AUTHENTICATED"
    },
    "consumerEmailAddressRequested": true,
    "consumerNameRequested": true,
    "consumerPhoneNumberRequested": true,
    "cardholderNameRequested": true,
    "consumerNationalIdentifierRequested": true,
    "dpaAcceptedBillingCountries": [],
    "acquirerMerchantId": "string",
    "acquirerBin": "123456",
    "merchantName": "string",
    "paymentOptions": [
      {
        "dynamicDataType": "CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM"
      }
    ]
  }
}
		

Sample Response

{
    "srcCorrelationId": "5C8E8754E800R2b3c3ed4-97f1-753d-54a2-1a08d44ad401",
    "srciTransactionId": "14744809-1b67-45dd-9bfb-12910f5f2ad9",
    "maskedConsumer": {
        "srcConsumerId": "1febd823-6392-fa8a-dc45-11a262cc4a01",
        "maskedConsumerIdentity": {
            "identityType": "EMAIL_ADDRESS",
            "maskedIdentityValue": "tes**@yopmail.com"
        },
        "maskedEmailAddress": "tes**@yopmail.com",
        "maskedMobileNumber": {
            "countryCode": "1",
            "phoneNumber": "5652"
        },
        "countryCode": "US",
        "languageCode": "en-US",
        "status": "ACTIVE",
        "maskedFirstName": "P",
        "maskedLastName": "T**",
        "maskedFullName": "P*****"
    },
    "maskedCard": {
        "srcDigitalCardId": "fa88832cda834e36e45c1e844fae7c01",
        "panBin": "414778",
        "panLastFour": "0745",
        "tokenBinRange": "464050733",
        "tokenLastFour": "0069",
        "tokenId": "ea01b1b60a317be587c418a7969d9301",
        "digitalCardData": {
            "status": "PENDING",
            "descriptorName": "longDescription",
            "artUri": "https://qa.assets.vims.visa.com/vims/cardart/0962c
844f27e4a83b912ad5545518d9d.png",
            "artHeight": 968,
            "artWidth": 1536,
            "pendingEvents": [
                "PENDING_CARDHOLDER_AUTHENTICATION"
            ],
            "authenticationMethods": [
                {
                    "authenticationMethodType": "SRCS_HOSTED_AUTHENTICATION",
                    "authenticationSubject": "CARDHOLDER",
                    "uriData": {
                        "uri": "https://b2cp-vco-dev2b-2.oce-np-sm-ddp-p-
en.trusted.visa.com/
checkout-widget/stepup/b2b-integration",
                        "uriType": "WEB_URI"
                    }
                }
            ]
        },
        "panExpirationMonth": "10",
        "panExpirationYear": "2029",
        "paymentCardDescriptor": "longDescription",
        "paymentCardType": "Credit Card",
        "countryCode": "US",
        "maskedBillingAddress": {
            "addressId": "cc912b29-8b5a-36ef-3698-1f1cb5145a01",
            "line1": "801*****",
            "city": "Fos*****",
            "state": "CA",
            "countryCode": "US",
            "zip": "944*****"
        },
        "paymentAccountReference": "V0010013825314391699431661850",
        "dateOfCardCreated": 1767742548509
    }
}
		

Payload Retrieval

The Payload Retrieval capability allows retrieval of payment data and payment‑related information required for payment authorization using the GET /transactions/credentials endpoint. Payload retrieval is typically performed after checkout when the checkout response does not include a FULL payload suitable for authorization, such as when a SUMMARY or NON_PAYMENT payload type is used.

Payload retrieval using GET /transactions/credentials may only be performed by a Payment SRCi. Retrieving a FULLorPAYMENT payload using this endpoint must only be done by Payment SRCis. If the SRCi is operating in a Non‑Payment SRCi role, payload retrieval must be performed by the SRCi’s payment facilitator, payment processor, or gateway (the entity responsible for transaction processing).

This capability is commonly used to obtain payment credentials required to complete authorization, including scenarios where payment data is pre‑stored or where downstream payment systems require an encrypted payload.

Use Cases:

Payload retrieval supports the following use cases:

  • Card‑on‑file transactions where payment data is pre‑stored
  • Retrieving payment credentials to complete checkout
  • Obtaining encrypted payloads for downstream payment processing systems

Payload Types:

Using GET /transactions/credentials, the following payload types may be retrieved:

  • FULL – Contains payment credentials and related transaction data required for authorization
  • PAYMENT – Contains payment credentials required for authorization without additional consumer data

Retrieval of FULL or PAYMENT payloads using this endpoint is restricted to Payment SRCis.

Cryptogram Details:

Payloads returned from GET /transactions/credentials may include the following EMVCo cryptogram types:

  • CARDHOLDER_AUTHENTICATION_CRYPTOGRAM
  • CARD_APPLICATION_CRYPTOGRAM_LONG_FORM
  • CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM

An encryptedSignedPayload contains either:

  • CARD_APPLICATION_CRYPTOGRAM_LONG_FORM, or
  • CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM

In addition, the payload may also include a CARDHOLDER_AUTHENTICATION_CRYPTOGRAM alongside the LONG or SHORT FORM cryptogram.

Workflow:

  1. Initiate payload retrieval

    A Payment SRCi initiates payload retrieval by calling Payload Retrieval (GET /transactions/credentials), providing:

    • srcCorrelationId or srcDigitalCardId

    • payloadTypeIndicator=FULL (or PAYMENT, if applicable)

  2. Validate SRCi role

    Visa Click to Pay validates that the caller is acting in the Payment SRCi role and is authorized to retrieve FULL or PAYMENT payloads.

  3. Validate request parameters

    Visa Click to Pay validates the request parameters, including the transaction identifier and requested payload type.

  4. Retrieve payment credentials

    Visa Click to Pay retrieves the required payment data, including the token and applicable cryptogram(s), for the identified transaction.

  5. Assemble encrypted payload
  6. Visa Click to Pay assembles the encrypted payload (encryptedPayload) containing the payment credentials and associated transaction data.

  7. Return payload response

    Visa Click to Pay returns a successful response to the Payment SRCi, including:

    encryptedPayload

    • The applicable Electronic Commerce Indicator (ECI)

  8. Submit payment authorization

    The Payment SRCi submits the authorization request to the payment processor (gateway or acquirer) using the retrieved payload.

  9. Receive authorization result

    The payment processor returns the authorization result (approved or declined) to the Payment SRCi.

 

Payload Retrieval API Details

Endpoint Details

Endpoint Name: GetPayload

Method: GET

Endpoint: /transaction/credentials

Refer to the API specifications for the complete request and response and any additional details.

Sample Request

{
    "srcClientId": "3EY722QTUPZCY5X5A3IY21OLy4te0ZTO9KB3PJMW9ugdQ3ZAQ",
    "srcCorrelationId": "5C8E8754E800R2b3c3ed4-97f1-753d-54a2-1a08d44ad401",
    "payloadTypeIndicator": "FULL"
}
		

Sample Response

{
    "payloadResponse": {
        "srcCorrelationId": "5C8E8754E800R2b3c3ed4-97f1-753d-54a2-1a08d44ad401",
        "srciTransactionId": "14744809-1b67-45dd-9bfb-12910f5f2ad9",
        "maskedConsumer": {
            "srcConsumerId": "1febd823-6392-fa8a-dc45-11a262cc4a01",
            "maskedConsumerIdentity": {
                "identityType": "EMAIL_ADDRESS",
            }
        },
        "maskedCard": {
            "srcDigitalCardId": "fa88832cda834e36e45c1e844fae7c01",
            "panBin": "414778",
            "panLastFour": "0745",
            "digitalCardData": {
                "status": "ACTIVE"
            }
        },
        "assuranceData": {
            "eci": "05",
            "verificationData": [
                {
                    "verificationType": "CARDHOLDER",
                    "verificationEntity": "03",
                    "verificationEvents": [
                        "01"
                    ],
                    "verificationMethod": "01",
                    "verificationResults": "01",
                    "verificationTimestamp": "1770189908889"
                }
            ]
        }
    },
    "encryptedPayload": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ.payloadJWE.signature"
}
		

Transaction Confirmation

The Transaction Confirmation capability is used to notify Visa Click to Pay of the final outcome of a checkout or payment authorization. Transaction Confirmation ensures that Visa Click to Pay is informed of whether a transaction was successfully authorized or declined.

Both Payment SRCis and Non‑Payment SRCis may perform Transaction Confirmation using the POST /confirmations endpoint.

Prerequisites:

  • Authentication successful
  • Payment facilitator or Payment SRCi has retrieved payload (see Get Payload)
  • assuranceData available (if authentication was performed)

Workflow:

  1. Submit authorization request

    The SRCi submits a payment authorization request to the payment processor or acquirer using the retrieved payment credentials.

  2. Authorization processing

    The payment processor processes the authorization request and returns one of the following outcomes:

    • Approved – Transaction authorized

    • Declined – Transaction declined by issuer

  3. Handle authorization outcome

    On approval:

    • Update order status to Confirmed
    • Send confirmation to the consumer
    • Initiate fulfillment
    • Store the transaction reference
    • Optionally proceed to account creation

    On decline:

    • Update order status to Failed
    • Notify the consumer of the decline
    • Offer retry or an alternative payment method
    • Log the failure reason for analysis
  4. Notify Visa Click to Pay

    The SRCi notifies Visa Click to Pay of the checkout or payment authorization result by calling the Transaction Confirmation endpoint (POST /confirmations), including the event type and authorization outcome.

  5. Confirmation response

    Visa Click to Pay records the transaction confirmation and returns a response to the SRCi.

  6. Consumer notification

    The SRCi displays the final success or failure status to the consumer.

     

    Transaction Confirmation ensures Visa Click to Pay has an accurate record of the transaction outcome. This step does not authorize a transaction; it records the result of authorization processing performed by the payment processor.

Transaction Confirmation API Details

Endpoint Details

Endpoint Name: Create Confirmation

Method: POST

Endpoint: /confirmations

Refer to the API specifications for the complete request and response and any additional details.

Sample Request

{
    "srcClientId": "3EY722QTUPZCY5X5A3IY21OLy4te0ZTO9KB3PJMW9ugdQ3ZAQ",
    "srcCorrelationId": "5C8E8754E800R2b3c3ed4-97f1-753d-54a2-1a08d44ad401",
    "confirmationData": {
        "checkoutEventType": "01",
        "confirmationStatus": "01",
        "confirmationTimestamp": "1770191200123",
        "networkAuthorizationCode": "A12345",
        "networkTransactionIdentifier": "9876543210"
    }
}
		

Sample Response

{
    "srcCorrelationId": "5C8E8754E800R2b3c3ed4-97f1-753d-54a2-1a08d44ad401"
}