- HTTP request
- Request body
- Response body
- MinimumRequiredCardInfo
- EnrollmentRiskSignals
- CustomerRiskDetails
- CustomerActionType
- AccountAgeBucket
- TermsOfServiceAcceptance
- CustomerDetails
- EnrollResponse
- EnrollResult
- EnrollSuccessResult
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 |
---|
{ "requestHeader": { object ( |
Fields | |
---|---|
requestHeader |
REQUIRED: Common header for all requests. This header contains the The same card can be enrolled multiple times, either by multiple users (different If a card is enrolled, un-enrolled, then enrolled again for Virtual Cards, the new enrollment will have a new |
cardToEnroll |
REQUIRED: The card to enroll in Virtual Cards. |
riskSignals |
REQUIRED: The risk signals used by the vendor to make a risk assessment. |
customerDetails |
REQUIRED Details about the customer. |
Union field terms_of_service . REQUIRED: Details about the customer terms of service interactions. Exactly one must be set. terms_of_service can be only one of the following: |
|
googleManagedAcceptanceDetails |
The presence of this field indicates that the customer accepted the terms of service. This contains additional information gathered when they accepted. |
externallyManagedAcceptance |
The presence of this field indicates that the 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 |
|
HTTP 4XX / 5XX Status |
|
MinimumRequiredCardInfo
FPAN representation of a card with an expiration date. No CVN.
JSON representation |
---|
{ "accountNumber": { object ( |
Fields | |
---|---|
accountNumber |
REQUIRED: The account number itself (i.e., the FPAN). |
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 |
---|
{ "commonRiskSignals": { object ( |
Fields | |
---|---|
commonRiskSignals |
REQUIRED Common request risk signals. |
customerRiskDetails |
REQUIRED Details about the customer. |
Union field |
|
panSourceWeb |
The PAN was sourced on a web browser. |
panSourceAndroid |
The PAN was sourced on an Android client. |
panSourceIos |
The PAN was sourced on an iOS client. |
panSourceUnknown |
The source of the PAN is unknown. |
CustomerRiskDetails
Details about the customer.
JSON representation |
---|
{ "hashedEmailAddress": string, "customerActionType": enum ( |
Fields | |
---|---|
hashedEmailAddress |
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 |
REQUIRED: The action the customer took to trigger the enrollment. |
accountAge |
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 end-user accepted the terms of service. This contains additional information gathered when they accepted.
JSON representation |
---|
{
"acceptanceTimestamp": {
object ( |
Fields | |
---|---|
acceptanceTimestamp |
REQUIRED: The timestamp when the user accepted the Terms of Service. |
version |
REQUIRED: The version of the Terms of Service the user accepted. |
CustomerDetails
Details about the customer.
JSON representation |
---|
{ "maskedEmailAddress": string } |
Fields | |
---|---|
maskedEmailAddress |
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 ( |
Fields | |
---|---|
responseHeader |
REQUIRED: Common header for all responses. |
result |
REQUIRED: Contains the result of the request. |
EnrollResult
Details corresponding to the result.
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field result . Contains the possible result types. Exactly one must be set. result can be only one of the following: |
|
success |
The request to |
invalidCardDetails |
DEPRECATED: All decline cases covered by this case should instead be covered by Declined because the card details, while formatted correctly, were invalid. (e.g. The expiration date did not match). |
cardIneligible |
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 |
Declined for risk reasons. |
tosNotAccepted |
Declined because the customer has not accepted the Terms of Service. This result is only applicable if the Terms of Service was not surfaced through Google, i.e. the request contained 'externallyManagedAcceptance'. |
tosAcceptanceOutdated |
Declined because too much time has passed since the customer's acceptance of the Terms of Service and the enrollment attempt. This result is only applicable if the Terms of Service was not surfaced through Google, i.e. the request contained 'externallyManagedAcceptance'. |
cardAccountClosed |
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 |
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 |
Declined because the PAN was unrecognized. |
incorrectExpiration |
Declined because the expiration was incorrect. |
EnrollSuccessResult
This type has no fields.
Details about the success result.