Method: retrieveVirtualCardNumber

Retrieves a virtual card number for a card enrolled in Virtual Cards.

An example request looks like this:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "requestId": "BKD0GF23KSD8S23",
    "requestTimestamp": {
      "epochMillis": "1481899949606"
    },
    "paymentIntegratorAccountId": "abcdef123456"
  },
  "enrollmentRequestId": "G1MQ0YERJ0Q7LPM",
  "merchantDetails": {
    "merchantDomainName": "https://www.gap.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"
      }
    },
    "challengeRecommended": {}
  }
}

An example challengeRequired response looks like this:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": "1481899950236"
    }
  },
  "result": {
    "challengeRequired": {
      "challengeOptions": [
        {
          "challengeOptionId": "ALFKJSG2352",
          "platformAuthentication": {}
        },
        {
          "challengeOptionId": "KLHL252LKJJ",
          "smsOtp": {
             "maskedPhoneNumber": "(***)-***-1212"
          }
        },
        {
          "challengeOptionId": "QJF3295JGSA",
          "smsOtp": {
             "maskedPhoneNumber": "(***)-***-3434"
          }
        },
        {
          "challengeOptionId": "GCAO261QRTS",
          "emailOtp": {
             "maskedEmailAddress": "a***b@gmail.com"
          }
        },
        {
          "challengeOptionId": "BQT3143SAF1",
          "emailOtp": {
             "maskedEmailAddress": "c***d@gmail.com"
          }
        },
        {
          "challengeOptionId": "SKDZ384SJDID",
          "cardSecurityCode": {
             "cardSecurityCodeType": "CARD_SECURITY_CODE_TYPE_CVV2",
             "maxVerificationAttempts": "3"
          }
        }
      ]
    }
  }
}

An example request with challenge results looks like this:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "requestId": "BKD0GF23KSD8S23",
    "requestTimestamp": {
      "epochMillis": "1481899949606"
    },
    "paymentIntegratorAccountId": "abcdef123456"
  },
  "enrollmentRequestId": "G1MQ0YERJ0Q7LPM",
  "merchantDetails": {
    "merchantDomainName": "https://www.gap.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"
      }
    },
    "challengeRecommended": {}
  },
  "challengeResultDetails": {
    "challengeResults": [
        {
          "challengeOptionId":"ALFKJSG2352",
          "platformAuthentication": {}
        },
        {
          "challengeOptionId":"KLHL252LKJJ",
          "otp": {
            "oneTimePassword": "111111"
          }
        },
        {
          "challengeOptionId":"SKDZ384SJDID",
          "cardSecurityCode": {
            "cardSecurityCode": "123"
          }
        }
    ]
  }
}

An example success response looks like this:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": "1481899950236"
    }
  },
  "result": {
    "success" :{
      "virtualCard": {
        "accountNumber": {
          "value": "2222444466668888"
        },
        "expiryDate": {
          "expiryMonth": "09",
          "expiryYear": "26"
        },
        "cvn": "246"
      }
    }
  }
}

For an overview of the challenge flow, see yellow path retrieval diagrams.

HTTP request

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

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "enrollmentRequestId": string,
  "merchantDetails": {
    object (MerchantDetails)
  },
  "riskSignals": {
    object (RetrieveVirtualCardNumberRiskSignals)
  },
  "challengeResultDetails": {
    object (ChallengeResultDetails)
  }
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
enrollmentRequestId

string

REQUIRED: A reference to an earlier enrollment request. Specifically, the identifier set in the requestId of the requestHeader sent in the enrollRequest that registered a card for Virtual Cards.

This is a string that has a maximum length of 100 characters.
merchantDetails

object (MerchantDetails)

REQUIRED: Details about the merchant that will accept the virtual card number.
riskSignals

object (RetrieveVirtualCardNumberRiskSignals)

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

object (ChallengeResultDetails)

OPTIONAL Challenge result information, provided after the user completes any requested challenges. The presence indicates the user has completed, or attempted to complete a given challenge.

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 (RetrieveVirtualCardNumberResponse)
HTTP 4XX / 5XX Status

object (ErrorResponse)

MerchantDetails

Details about a merchant that will accept the virtual card.

JSON representation 
{

  // Union field merchantOrigin can be only one of the following:
  "appPackageName": string,
  "merchantDomainName": string
  // End of list of possible types for union field merchantOrigin.
}
Fields
Union field merchantOrigin. The origin of the merchant. Exactly one must be set. merchantOrigin can be only one of the following:
appPackageName

string

The merchant's app package name where the virtual card number will be used.
merchantDomainName

string

The merchant's domain from the web URL where the virtual card number will be used.

RetrieveVirtualCardNumberRiskSignals

Information used by the vendor to make risk assessment about a virtual card number retrieval.

JSON representation 
{
  "commonRiskSignals": {
    object (RiskSignals)
  },

  // Union field RecommendationDecision can be only one of the following:
  "challengeNotRecommended": {
    object (Empty)
  },
  "challengeRecommended": {
    object (Empty)
  }
  // End of list of possible types for union field RecommendationDecision.
}
Fields
commonRiskSignals

object (RiskSignals)

REQUIRED Common request risk signals.

Union field RecommendationDecision. REQUIRED: Google's recommendation decision about the overall risk assessment.

RecommendationDecision can be only one of the following:

ChallengeResultDetails

Information on any challenge results submitted with the request.

JSON representation 
{
  "challengeResults": [
    {
      object (ChallengeResult)
    }
  ]
}
Fields
challengeResults[]

object (ChallengeResult)

REQUIRED The list of challenge results.

ChallengeResult

Details about a specific challenge result.

JSON representation 
{
  "challengeOptionId": string,

  // Union field challenge_option_details can be only one of the following:
  "platformAuthentication": {
    object (Empty)
  },
  "otp": {
    object (OtpChallengeResult)
  },
  "cardSecurityCode": {
    object (CardSecurityCodeChallengeResult)
  }
  // End of list of possible types for union field challenge_option_details.
}
Fields
challengeOptionId

string

REQUIRED: The globally unique reference identifying a specific challenge option.

This is a string that has a maximum length of 100 characters. Valid characters: [a-zA-Z0-9:_-]
Union field challenge_option_details. The challenge-specific details. Exactly one must be set. challenge_option_details can be only one of the following:
platformAuthentication

object (Empty)

A platform authentication verified by Google.
otp

object (OtpChallengeResult)

An OTP result received from an out-of-band communication.
cardSecurityCode

object (CardSecurityCodeChallengeResult)

A card security code input by the user.

OtpChallengeResult

The result details of an OTP challenge.

JSON representation 
{
  "oneTimePassword": string
}
Fields
oneTimePassword

string

REQUIRED The OTP as submitted by the user for verification. The format is 6-digit numerical.

CardSecurityCodeChallengeResult

The result details of a card security code challenge.

JSON representation 
{
  "cardSecurityCode": string
}
Fields
cardSecurityCode

string

REQUIRED The card security code as submitted by the user for verification. The format is 3-5 numerical digits.

RetrieveVirtualCardNumberResponse

Response object for the retrieveVirtualCardNumber method.

JSON representation 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "result": {
    object (RetrieveVirtualCardNumberResult)
  }
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

object (RetrieveVirtualCardNumberResult)

REQUIRED: Contains the result of the request.

RetrieveVirtualCardNumberResult

Details corresponding to the result.

JSON representation 
{

  // Union field result can be only one of the following:
  "success": {
    object (RetrieveVirtualCardNumberSuccessResult)
  },
  "riskDeclined": {
    object (Empty)
  },
  "cardIneligible": {
    object (Empty)
  },
  "challengeRequired": {
    object (ChallengeRequiredDeclinedResult)
  },
  "challengeResultInvalid": {
    object (ChallengeResultInvalidDeclinedResult)
  },
  "challengeResultExpired": {
    object (ChallengeResultExpiredDeclinedResult)
  },
  "challengeResultVerificationLimitExceeded": {
    object (ChallengeResultRetryExceededDeclinedResult)
  }
  // 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 (RetrieveVirtualCardNumberSuccessResult)

The request to retrieveVirtualCardNumber was successful the virtual card number was procured.
riskDeclined

object (Empty)

Declined for risk reasons.
cardIneligible

object (Empty)

Declined because the given enrollment is ineligible to retrieve a virtual card number.
challengeRequired

object (ChallengeRequiredDeclinedResult)

The payment integrator requires a challenge to retrieve the virtual card number.
challengeResultInvalid

object (ChallengeResultInvalidDeclinedResult)

A provided challenge result has an invalid value.
challengeResultExpired

object (ChallengeResultExpiredDeclinedResult)

A provided challenge result exceeded the time limit.
challengeResultVerificationLimitExceeded

object (ChallengeResultRetryExceededDeclinedResult)

A provided challenge result exceeded the retry limit.

RetrieveVirtualCardNumberSuccessResult

Details about the success result.

JSON representation 
{
  "virtualCard": {
    object (VerifiableMinimumRequiredCardInfo)
  }
}
Fields
virtualCard

object (VerifiableMinimumRequiredCardInfo)

REQUIRED: Contains the virtual card number information.

VerifiableMinimumRequiredCardInfo

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

JSON representation 
{
  "accountNumber": {
    object (AccountNumber)
  },
  "expiryDate": {
    object (ExpiryDate)
  },
  "cvn": string
}
Fields
accountNumber

object (AccountNumber)

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

object (ExpiryDate)

REQUIRED: Expiration date, month and year.
cvn

string

REQUIRED: The card verification number (CVN) for the given accountNumber.

This is a string of 3-4 digits.

ChallengeRequiredDeclinedResult

Details about a challenge required result.

JSON representation 
{
  "challengeOptions": [
    {
      object (ChallengeOption)
    }
  ]
}
Fields
challengeOptions[]

object (ChallengeOption)

REQUIRED a list of challenges the user can complete in order to authenticate.

ChallengeOption

Details about a specific challenge option the user can complete in order to authenticate.

JSON representation 
{
  "challengeOptionId": string,

  // Union field challenge_option_details can be only one of the following:
  "platformAuthentication": {
    object (Empty)
  },
  "smsOtp": {
    object (SmsOtpChallengeOption)
  },
  "emailOtp": {
    object (EmailOtpChallengeOption)
  },
  "cardSecurityCode": {
    object (CardSecurityCodeChallengeOption)
  }
  // End of list of possible types for union field challenge_option_details.
}
Fields
challengeOptionId

string

REQUIRED: The globally unique reference identifying a specific challenge option.

This is a string that has a maximum length of 100 characters. Valid characters: [a-zA-Z0-9:_-]
Union field challenge_option_details. The challenge-specific details. Exactly one must be set. challenge_option_details can be only one of the following:
platformAuthentication

object (Empty)

A platform authentication verified by Google.
smsOtp

object (SmsOtpChallengeOption)

A one-time password transmitted via SMS.
emailOtp

object (EmailOtpChallengeOption)

A one-time password transmitted via email.
cardSecurityCode

object (CardSecurityCodeChallengeOption)

A verification of a security code printed on the user's card.

SmsOtpChallengeOption

A one-time password transmitted via SMS.

JSON representation 
{
  "maskedPhoneNumber": string
}
Fields
maskedPhoneNumber

string

REQUIRED The masked phone number the SMS OTP will be sent to. If the user has multiple phone numbers that can be used for SMS OTP challenges, partners should return multiple ChallengeOption objects with the smsOtp field set.

The phone number masking format is: "[()*-]*[0-9]{4}" - The last four digits are displayed. - The remaining digits are replaced with the character '*'. - The characters "-" "(" and ")"are allowed for formatting. ex: "(***)-***-1234".

EmailOtpChallengeOption

A one-time password transmitted via email.

JSON representation 
{
  "maskedEmailAddress": string
}
Fields
maskedEmailAddress

string

REQUIRED The masked email address the email OTP will be sent to. If the user has multiple email addresses that can be used for email OTP challenges, partners should return multiple ChallengeOption objects with the emailOtp field set.

Three asterisks should be used to mask the characters between the first and last characters of the email address username. Fewer asterisks should be used for usernames shorter than 5 characters. Examples:

  • abcdefghijk@gmail.com → a***k@gmail.com
  • abcde@gmail.com → a***e@gmail.com
  • abcd@gmail.com → a**d@gmail.com
  • abc@gmail.com → a*c@gmail.com
  • ab@gmail.com → a*@gmail.com
  • a@gmail.com → *@gmail.com

CardSecurityCodeChallengeOption

A verification of a security code printed on the user's card.

JSON representation 
{
  "maxVerificationAttempts": string,
  "cardSecurityCodeType": enum (CardSecurityCodeType)
}
Fields
maxVerificationAttempts

string (Int64Value format)

REQUIRED The maximum number of times a card security code can be submitted for verification for this challenge option.
cardSecurityCodeType

enum (CardSecurityCodeType)

REQUIRED: The type of the card security code that is being requested from the user.

CardSecurityCodeType

The type of the card security code.

Enums
CARD_SECURITY_CODE_TYPE_UNSPECIFIED DO NOT USE
CARD_SECURITY_CODE_TYPE_CVV2 The security code is a CVV2. This is also known as the CVN, CVV, CVC, CID, etc.
CARD_SECURITY_CODE_TYPE_3CSC The security code is a 3CSC. For example, the 3-digit code on the back of American Express cards.
CARD_SECURITY_CODE_TYPE_XID The security code is an XID. For example, the 5 digit code on the back of Discover cards.

ChallengeResultInvalidDeclinedResult

Details about an invalid challenge response result.

JSON representation 
{
  "challengeOptionId": string
}
Fields
challengeOptionId

string

REQUIRED: The challenge option ID of the invalid challenge response.

ChallengeResultExpiredDeclinedResult

Details about a challenge response expired result.

JSON representation 
{
  "challengeOptionId": string
}
Fields
challengeOptionId

string

REQUIRED: The challenge option ID of the invalid challenge response.

ChallengeResultRetryExceededDeclinedResult

Details about a challenge response retry exceeded result.

JSON representation 
{
  "challengeOptionId": string
}
Fields
challengeOptionId

string

REQUIRED: The challenge option ID of the invalid challenge response.