Virtual Cards diagrams

The following sequence diagrams show how user, Google, and the Payment Integrator interact to provide the following Virtual Cards functionalities:


Enrollmment sequence diagram

Virtual Cards enrollment is executed only once during the lifetime of a virtual card number (VCN). The enrollment can be initiated in different ways: when (i) user saves the payment information during checkout for the first time (upstream enrollment), (ii) user makes a purchase online with a non-virtual card (downstream enrollment) or (iii) user enables the virtual card number at

After the enrollment is initiated by the user, Google Pay Autofill returns Terms of Service (ToS) and asks user consent to proceed. In case the consent is obtained, Google calls the enroll API, informing requestId, cardToEnroll and riskSignals so that the Integrator decides on whether or not to allow the enrollment. If the enrollment succeeds, a virtual card number option is shown in Google Pay Autofill during the checkout.


After the enrollment, whenever the user selects a virtual card number in Google Pay Autofill the retrieval flow is initiated as illustrated below (green path).

Retrieval sequence diagram Green Path

As illustrated, after the virtual card selection, Google calls the retrieveVirtualCardNumber API informing enrollmentRequestId (equal to requestId sent in the enrollment), merchantDetails and riskSignals so that the Integrator can assess the context of the virtual card number request and decide to:

  • accept (green path), by returning the virtual card number (diagram above),
  • step up (yellow path), using an available Identity & Verification (ID&V) method, or
  • decline (red path) the request.

Yellow and red path flows are shown in the next sections.

Yellow path retrieval

Yellow path retrieval flow adopting the Platform Authenticator ID&V method is illustrated in the next sequence diagram. In this example, given the Integrator returns both platformAuthentication and smsOtp as challengeOptions, Google prioritizes platformAuthentication and, consequently, does not show ID&V selector UI.

Retrieval sequence diagram Platform Auth

Yellow path with SMS OTP ID&V method is shown below. Note that in this case Google calls the sendOtp API to request the Integrator to send an OTP to the user. The OTP delivery happens 'out of band' from Google perspective. Once the user receives the OTP from the Integrator, it can enter its value in Google Pay Autofill.

Retrieval sequence diagram OTP

Red path retrieval

Red path retrieval flow is represented below. In this case the Integrator decides to decline the virtual card number request.

Retrieval sequence diagram Red Path


Enrolled Virtual Cards can be unenrolled as illustrated in the diagram below. Google calls the unenroll API informing enrollmentRequestId whose value is equal to requestId sent in the corresponding enrollment.

Unenrollment sequence diagram

Transaction management

Virtual Cards transactions are also provided by the Integrator as shown by the following diagram:

Transaction sequence diagram

Initially, the Integrator notifies Google using the transactionEventNotification API, indicating that a transaction event occurred for an enrolled virtual card. In turn, Google calls getTransactions to retrieve a list of transactions for the given virtual card number.

The transactionListContinuationToken field can be provided to limit the returned transactions to those that have been added or updated since the request represented by this token. If the token is not provided, the response should include all transactions for the maximum period prior to the request.