Method: enroll

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 (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)

REQUIRED Details 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
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 
{
  "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)

REQUIRED Common request risk signals.
customerRiskDetails

object (CustomerRiskDetails)

REQUIRED Details 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
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
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
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
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 
{

  // 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. 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.

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.