Method: enroll

Page Summary

Enrolls a card in Virtual Cards using the enroll method with a POST request.
The request body requires card details, risk signals, and customer details.
Risk signals are used to assess the risk of enrolling the card.
The response indicates success or provides a reason for decline, such as invalid card details, risk assessment, or terms of service.
Successful enrollment allows the card to be used with Virtual Cards.

Enrolls a card in Virtual Cards.

An example request looks like:

  { 
  
 "requestHeader" 
 : 
  
 { 
  
 "protocolVersion" 
 : 
  
 { 
  
 "major" 
 : 
  
 1 
  
 } 
 , 
  
 "requestId" 
 : 
  
 "G1MQ0YERJ0Q7LPM" 
 , 
  
 "requestTimestamp" 
 : 
  
 { 
  
 "epochMillis" 
 : 
  
 "1481899949606" 
  
 } 
 , 
  
 "paymentIntegratorAccountId" 
 : 
  
 "abcdef123456" 
  
 } 
 , 
  
 "googleManagedAcceptanceDetails" 
 : 
  
 { 
  
 "acceptanceTimestamp" 
 : 
  
 { 
  
 "epochMillis" 
 : 
  
 "1481899949657" 
  
 } 
 , 
  
 "version" 
 : 
  
 "1.1" 
  
 } 
 , 
  
 "cardToEnroll" 
 : 
  
 { 
  
 "accountNumber" 
 : 
  
 { 
  
 "value" 
 : 
  
 "1111222233334444" 
  
 } 
 , 
  
 "expiryDate" 
 : 
  
 { 
  
 "expiryMonth" 
 : 
  
 "11" 
 , 
  
 "expiryYear" 
 : 
  
 "25" 
  
 } 
  
 } 
 , 
  
 "customerDetails" 
 : 
  
 { 
  
 "maskedEmailAddress" 
 : 
  
 "l***r@gmail.com" 
  
 } 
 , 
  
 "riskSignals" 
 : 
  
 { 
  
 "commonRiskSignals" 
 : 
  
 { 
  
 "environmentalDetails" 
 : 
  
 { 
  
 "ipAddress" 
 : 
  
 "192.168.1.1" 
 , 
  
 "actionContext" 
 : 
  
 "NATIVE_APP" 
 , 
  
 "deviceGeoLocation" 
 : 
  
 { 
  
 "latitudeE7" 
 : 
  
 "396317000" 
 , 
  
 "longitudeE7" 
 : 
  
 "-86733000" 
  
 } 
  
 } 
 , 
  
 "physicalDetails" 
 : 
  
 { 
  
 "deviceToAccountBindingId" 
 : 
  
 "0bba7f1e4a83ab4fdd77f5ebd6bd4495905f36db9c7c6e638833721e181bd837" 
 , 
  
 "devicePhoneNumberLastFour" 
 : 
  
 "1234" 
 , 
  
 "deviceAccountAge" 
 : 
  
 "LESS_THAN_SEVEN_DAYS" 
 , 
  
 "android" 
 : 
  
 {} 
 , 
  
 "devicePlatformAuthenticatorEnabled" 
 : 
  
 {} 
  
 } 
 , 
  
 "googleAccountDetails" 
 : 
  
 { 
  
 "mostRecentAccountPaymentMethodChangeActivity" 
 : 
  
 "MOST_RECENT_ACCOUNT_PAYMENT_METHOD_CHANGE_ACTIVITY_LESS_THAN_ONE_DAY" 
 , 
  
 "mostRecentAccountSecurityActivity" 
 : 
  
 "MOST_RECENT_ACCOUNT_SECURITY_ACTIVITY_LESS_THAN_ONE_DAY" 
 , 
  
 "accountAndCardNameMatch" 
 : 
  
 {} 
 , 
  
 "customerPhoneNumberLastFour" 
 : 
  
 "1234" 
 , 
  
 "autofillPaymentMethodAttempts" 
 : 
  
 "42" 
 , 
  
 "cardAge" 
 : 
  
 "LESS_THAN_SEVEN_DAYS" 
 , 
  
 "numberOfBillingLastNames" 
 : 
  
 "7" 
  
 } 
 , 
  
 "googleRiskAssessment" 
 : 
  
 { 
  
 "deviceRiskScore" 
 : 
  
 "DEVICE_RISK_SCORE_MEDIUM" 
 , 
  
 "accountRiskScore" 
 : 
  
 "ACCOUNT_RISK_SCORE_HIGH" 
  
 } 
  
 } 
 , 
  
 "customerRiskDetails" 
 : 
  
 { 
  
 "hashedEmailAddress" 
 : 
  
 "a34fe89600bb813871c049ed50d323811cb3f6f4daeea88372014c90e350e688" 
 , 
  
 "customerActionType" 
 : 
  
 "NEW_CARD" 
 , 
  
 "accountAge" 
 : 
  
 "ACCOUNT_AGE_BUCKET_LESS_THAN_ONE_YEAR" 
  
 } 
 , 
  
 "panSourceWeb" 
 : 
  
 {} 
  
 } 
 }

An example success response looks like:

 {
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": "1481899950236"
    }
  },
  "result": {
    "success" :{
    }
  }
}

HTTP request

POST https://www.integratorhost.example.com/integrator-base-path/virtual-cards-v1/enroll

Request body

The request body contains data with the following structure:

JSON representation

JSON representation
{ "requestHeader" : { object ( `RequestHeader` ) } , "cardToEnroll" : { object ( `MinimumRequiredCardInfo` ) } , "riskSignals" : { object ( `EnrollmentRiskSignals` ) } , "customerDetails" : { object ( `CustomerDetails` ) } , // Union field `terms_of_service` can be only one of the following: "googleManagedAcceptanceDetails" : { object ( `TermsOfServiceAcceptance` ) } , "externallyManagedAcceptance" : { object ( `Empty` ) } // End of list of possible types for union field `terms_of_service` . }

 { 
 "requestHeader" 
 : 
 { 
 object (  RequestHeader 
 
) 
 } 
 , 
 "cardToEnroll" 
 : 
 { 
 object (  MinimumRequiredCardInfo 
 
) 
 } 
 , 
 "riskSignals" 
 : 
 { 
 object (  EnrollmentRiskSignals 
 
) 
 } 
 , 
 "customerDetails" 
 : 
 { 
 object (  CustomerDetails 
 
) 
 } 
 , 
 // Union field terms_of_service 
can be only one of the following: 
 "googleManagedAcceptanceDetails" 
 : 
 { 
 object (  TermsOfServiceAcceptance 
 
) 
 } 
 , 
 "externallyManagedAcceptance" 
 : 
 { 
 object (  Empty 
 
) 
 } 
 // End of list of possible types for union field terms_of_service 
. 
 }

Fields

requestHeader

object ( RequestHeader )

REQUIRED: Common header for all requests.

This header contains the requestId which is known as the enrollmentRequestId in other methods. It will be used in subsequent calls as a reference to the enrollment request which registered a card for Virtual Cards.

The same card can be enrolled multiple times, either by multiple users (different hashedEmailAddress ) or a single user (same hashedEmailAddress ) with multiple payment profiles .

If a card is enrolled, un-enrolled, then enrolled again for Virtual Cards, the new enrollment will have a new requestId .

cardToEnroll

object ( MinimumRequiredCardInfo )

REQUIRED: The card to enroll in Virtual Cards.

riskSignals

object ( EnrollmentRiskSignals )

REQUIRED: The risk signals used by the vendor to make a risk assessment.

customerDetails

object ( CustomerDetails )

REQUIREDDetails about the customer.

Union field terms_of_service . REQUIRED: Details about the customer's interactions with the partner's terms of service. Exactly one must be set. terms_of_service can be only one of the following:

googleManagedAcceptanceDetails

object ( TermsOfServiceAcceptance )

The presence of this field indicates that the customer accepted the partner's terms of service. This contains additional information gathered when they accepted.

externallyManagedAcceptance

object ( Empty )

The presence of this field indicates that the partner's terms of service was not surfaced through Google.

Response body

This method supports multiple return types. For additional information about what 4XX or 5XX HTTP status code to return with an ErrorResponse , consult the ErrorResponse object and HTTP status codes documentation .

Possible response messages
HTTP 200 Status	`object ( EnrollResponse )`
HTTP 4XX / 5XX Status	`object ( ErrorResponse )`

MinimumRequiredCardInfo

FPAN representation of a card with an expiration date. No CVN.

JSON representation
{ "accountNumber" : { object ( `AccountNumber` ) } , "expiryDate" : { object ( `ExpiryDate` ) } }

Fields

Fields
`accountNumber`	`object ( AccountNumber )` REQUIRED: The account number itself (i.e., the FPAN).
`expiryDate`	`object ( ExpiryDate )` REQUIRED: Expiration date, month and year.

accountNumber

object ( AccountNumber )

REQUIRED: The account number itself (i.e., the FPAN).

expiryDate

object ( ExpiryDate )

REQUIRED: Expiration date, month and year.

EnrollmentRiskSignals

Information used by the vendor to make risk assessment about enrolling the card in Virtual Cards.

JSON representation

JSON representation
{ "commonRiskSignals" : { object ( `RiskSignals` ) } , "customerRiskDetails" : { object ( `CustomerRiskDetails` ) } , // Union field `PanSourceIndicator` can be only one of the following: "panSourceWeb" : { object ( `Empty` ) } , "panSourceAndroid" : { object ( `Empty` ) } , "panSourceIos" : { object ( `Empty` ) } , "panSourceUnknown" : { object ( `Empty` ) } // End of list of possible types for union field `PanSourceIndicator` . }

 { 
 "commonRiskSignals" 
 : 
 { 
 object (  RiskSignals 
 
) 
 } 
 , 
 "customerRiskDetails" 
 : 
 { 
 object (  CustomerRiskDetails 
 
) 
 } 
 , 
 // Union field PanSourceIndicator 
can be only one of the following: 
 "panSourceWeb" 
 : 
 { 
 object (  Empty 
 
) 
 } 
 , 
 "panSourceAndroid" 
 : 
 { 
 object (  Empty 
 
) 
 } 
 , 
 "panSourceIos" 
 : 
 { 
 object (  Empty 
 
) 
 } 
 , 
 "panSourceUnknown" 
 : 
 { 
 object (  Empty 
 
) 
 } 
 // End of list of possible types for union field PanSourceIndicator 
. 
 }

Fields

commonRiskSignals

object ( RiskSignals )

REQUIREDCommon request risk signals.

customerRiskDetails

object ( CustomerRiskDetails )

REQUIREDDetails about the customer.

Union field PanSourceIndicator . REQUIRED: How the PAN was sourced by Google.

PanSourceIndicator can be only one of the following:

panSourceWeb

object ( Empty )

The PAN was sourced on a web browser.

panSourceAndroid

object ( Empty )

The PAN was sourced on an Android client.

panSourceIos

object ( Empty )

The PAN was sourced on an iOS client.

panSourceUnknown

object ( Empty )

The source of the PAN is unknown.

CustomerRiskDetails

Details about the customer.

JSON representation
{ "hashedEmailAddress" : string , "customerActionType" : enum ( `CustomerActionType` ) , "accountAge" : enum ( `AccountAgeBucket` ) }

Fields

Fields
`hashedEmailAddress`	`string` REQUIRED: A hash of the customer's email address. This is stable for the same email address across multiple enrollments. The value for a given email address will be different for different partners. This is a string that has 64 characters and contains only the characters "0-9" and "a-f".
`customerActionType`	`enum ( CustomerActionType )` REQUIRED: The action the customer took to trigger the enrollment.
`accountAge`	`enum ( AccountAgeBucket )` REQUIRED: Tenure of the Google account.

hashedEmailAddress

string

REQUIRED: A hash of the customer's email address. This is stable for the same email address across multiple enrollments. The value for a given email address will be different for different partners.

This is a string that has 64 characters and contains only the characters "0-9" and "a-f".

customerActionType

enum ( CustomerActionType )

REQUIRED: The action the customer took to trigger the enrollment.

accountAge

enum ( AccountAgeBucket )

REQUIRED: Tenure of the Google account.

CustomerActionType

The action the customer took to trigger the enrollment.

Enums
`CUSTOMER_ACTION_TYPE_UNSPECIFIED`	DO NOT USE
`PUSH_PROVISIONING`	When a customer enables a card in GPay from an issuer's platform.
`NEW_CARD`	When a customer enrolls a new card.
`EXISTING_CARD`	When a customer enrolls an existing card on file.

AccountAgeBucket

Tenure of the Google account.

Enums
`ACCOUNT_AGE_BUCKET_UNSPECIFIED`	DO NOT USE
`ACCOUNT_AGE_BUCKET_LESS_THAN_ONE_DAY`	The account age is less than one day.
`ACCOUNT_AGE_BUCKET_LESS_THAN_SEVEN_DAYS`	The account age is less than seven days.
`ACCOUNT_AGE_BUCKET_LESS_THAN_THIRTY_DAYS`	The account age is less than thirty days.
`ACCOUNT_AGE_BUCKET_LESS_THAN_ONE_YEAR`	The account age is less than one year (365 days).
`ACCOUNT_AGE_BUCKET_ONE_YEAR_OR_GREATER`	The account age is one year (365 days) or greater.

TermsOfServiceAcceptance

The presence of this field indicates that the customer accepted the partner's terms of service. This contains additional information gathered when they accepted.

JSON representation
{ "acceptanceTimestamp" : { object ( `Timestamp` ) } , "version" : string }

Fields

Fields
`acceptanceTimestamp`	`object ( Timestamp )` REQUIRED: The timestamp when the customer accepted the partner's terms of service.
`version`	`string` REQUIRED: The version of the partner's terms of service that the customer accepted.

acceptanceTimestamp

object ( Timestamp )

REQUIRED: The timestamp when the customer accepted the partner's terms of service.

version

string

REQUIRED: The version of the partner's terms of service that the customer accepted.

CustomerDetails

Details about the customer.

JSON representation
{ "maskedEmailAddress" : string }

Fields

Fields
`maskedEmailAddress`	`string` REQUIRED: The masked email of the customer enrolling the card. Used in the issuer's ecosystem to indicate to a customer which accounts have enrolled the card. Three asterisks are used to mask the symbols between the first and last symbols of an email address. (Ex: “l*** r@gmail.com” ) The result is not a valid email address.

maskedEmailAddress

string

REQUIRED: The masked email of the customer enrolling the card. Used in the issuer's ecosystem to indicate to a customer which accounts have enrolled the card. Three asterisks are used to mask the symbols between the first and last symbols of an email address. (Ex: “l*** r@gmail.com” ) The result is not a valid email address.

EnrollResponse

Response object for the enroll method.

JSON representation
{ "responseHeader" : { object ( `ResponseHeader` ) } , "result" : { object ( `EnrollResult` ) } }

Fields

Fields
`responseHeader`	`object ( ResponseHeader )` REQUIRED: Common header for all responses.
`result`	`object ( EnrollResult )` REQUIRED: Contains the result of the request.

responseHeader

object ( ResponseHeader )

REQUIRED: Common header for all responses.

result

object ( EnrollResult )

REQUIRED: Contains the result of the request.

EnrollResult

Details corresponding to the result.

JSON representation

JSON representation
{ // Union field `result` can be only one of the following: "success" : { object ( `EnrollSuccessResult` ) } , "invalidCardDetails" : { object ( `Empty` ) } , "cardIneligible" : { object ( `Empty` ) } , "riskDeclined" : { object ( `Empty` ) } , "tosNotAccepted" : { object ( `Empty` ) } , "tosAcceptanceOutdated" : { object ( `Empty` ) } , "cardAccountClosed" : { object ( `Empty` ) } , "panNoLongerValid" : { object ( `Empty` ) } , "unknownPan" : { object ( `Empty` ) } , "incorrectExpiration" : { object ( `Empty` ) } // End of list of possible types for union field `result` . }

 { 
 // Union field result 
can be only one of the following: 
 "success" 
 : 
 { 
 object (  EnrollSuccessResult 
 
) 
 } 
 , 
 "invalidCardDetails" 
 : 
 { 
 object (  Empty 
 
) 
 } 
 , 
 "cardIneligible" 
 : 
 { 
 object (  Empty 
 
) 
 } 
 , 
 "riskDeclined" 
 : 
 { 
 object (  Empty 
 
) 
 } 
 , 
 "tosNotAccepted" 
 : 
 { 
 object (  Empty 
 
) 
 } 
 , 
 "tosAcceptanceOutdated" 
 : 
 { 
 object (  Empty 
 
) 
 } 
 , 
 "cardAccountClosed" 
 : 
 { 
 object (  Empty 
 
) 
 } 
 , 
 "panNoLongerValid" 
 : 
 { 
 object (  Empty 
 
) 
 } 
 , 
 "unknownPan" 
 : 
 { 
 object (  Empty 
 
) 
 } 
 , 
 "incorrectExpiration" 
 : 
 { 
 object (  Empty 
 
) 
 } 
 // End of list of possible types for union field result 
. 
 }

Fields

Union field result . REQUIRED: Contains the possible result types. Exactly one must be set. result can be only one of the following:

success

object ( EnrollSuccessResult )

The request to enroll was successful and the card is enrolled in Virtual Cards.

invalidCardDetails

object ( Empty )

DEPRECATED: All decline cases covered by this case should instead be covered by cardAccountClosed , panNoLongerValid , unknownPan , or incorrectExpiration .

Note: This field will be removed once all usages of it has been migrated to other fields in the EnrollResult.result union field. ETA: H1 2024.

Declined because the card details, while formatted correctly, were invalid. (e.g. The expiration date did not match).

cardIneligible

object ( Empty )

Declined because the card was valid/active, but ineligible to be enrolled in Virtual Cards. The card could potentially become eligible at a future date.

riskDeclined

object ( Empty )

Declined for risk reasons.

tosNotAccepted

object ( Empty )

Declined because the customer has not accepted the partner's terms of service. This result is only applicable if the partner's terms of service was not surfaced through Google, i.e. the request contained 'externallyManagedAcceptance'.

tosAcceptanceOutdated

object ( Empty )

Declined because too much time has passed since the customer's acceptance of the partner's terms of service and the enrollment attempt. This result is only applicable if the partner's terms of service was not surfaced through Google, i.e. the request contained 'externallyManagedAcceptance'.

cardAccountClosed

object ( Empty )

Declined because the card account has been closed or is effectively closed (i.e. the underlying account with the financial institution is closed or in a similar terminal state, e.g. bankrupt). The user may still have other active card accounts with this financial institution.

panNoLongerValid

object ( Empty )

Declined because the PAN is no longer valid, i.e. the PAN is recognized but has been invalidated or updated (card lost, stolen, expired, etc). The underlying card account is still open (use cardAccountClosed otherwise).

unknownPan

object ( Empty )

Declined because the PAN was unrecognized.

incorrectExpiration

object ( Empty )

Declined because the expiration was incorrect.

EnrollSuccessResult

This type has no fields.

Details about the success result.

Method: enroll Stay organized with collections Save and categorize content based on your preferences.

Page Summary

HTTP request

Request body

Response body

MinimumRequiredCardInfo

EnrollmentRiskSignals

CustomerRiskDetails

CustomerActionType

AccountAgeBucket

TermsOfServiceAcceptance

CustomerDetails

EnrollResponse

EnrollResult

EnrollSuccessResult

Method: enroll