Method: authenticateIdentity

Authenticates a user's account using data about the user's Google account and current context. This authentication method can provide a seamless experience for the user by relying on data that has been verified ahead of time.

Any follow-up step relying on this authentication (like associateAccount or capture) will contain the authenticationRequestId from the authenticateIdentityRequest as proof of authentication.

If the endpoint encounters an error while processing the request, the response body from this endpoint should be of type ErrorResponse.

An example request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 1,
      "revision": 0
    },
    "requestId": "G112YZH4XPDV88J",
    "requestTimestamp": "1481907920000"
  },
  "authenticationRequestId": "1591303-231233235-151J",
  "associationId": "15522364553",
  "googleAccountAssertions": {
    "verifiedPhoneNumber": {
      "phoneNumber": "+12225551234",
      "lastVerificationTimestamp": "1481901920000",
      "verificationMethod": "CARRIER_API"
    }
  }
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": "1502545413132"
  },
  "paymentIntegratorAuthenticateIdentityId": "5539163",
  "result": "SUCCESS"
}

HTTP request

POST https://www.integratorhost.example.com/integrator-base-path/e-wallets-v1/authenticateIdentity

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "authenticationRequestId": string,
  "associationId": string,
  "googleAccountAssertions": {
    object (GoogleAccountAssertions)
  }
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
authenticationRequestId

string

REQUIRED: Identifier for this user authentication session. This value will appear in follow-up methods as proof of authentication.
associationId

string

OPTIONAL: This is the association identifier used to reference a user's account. If this is populated then it is expected that the integrator verify the values in googleAccountAssertions are not just correct for any user account, but are correct for the particular user account identified by this associationId.

This is populated whenever Google is performing a re-authentication of an already associated account.
googleAccountAssertions
(deprecated)

object (GoogleAccountAssertions)

DEPRECATED: This is information about the user's Google account that Google has verified somehow.

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

object (ErrorResponse)

GoogleAccountAssertions

JSON representation 
{
  "verifiedPhoneNumber": {
    object (VerifiedPhoneNumber)
  }
}
Fields
verifiedPhoneNumber

object (VerifiedPhoneNumber)

OPTIONAL: The phone number tied to the user's Google account and verified by Google using one of a number of possible verification methods.

VerifiedPhoneNumber

A phone number verified by Google as belonging to the user's Google account

JSON representation 
{
  "phoneNumber": string,
  "lastVerificationTimestamp": string,
  "verificationMethod": enum (VerificationMethod)
}
Fields
phoneNumber

string

REQUIRED: This is a E.164 formatted phone number. Examples include +14035551111 and +918067218000. This will always lead with a + and include only numbers afterwards (no dashes).
lastVerificationTimestamp

string (int64 format)

OPTIONAL: Timestamp of the last time that this phone number was verified by Google, expressed as milliseconds since epoch.
verificationMethod

enum (VerificationMethod)

OPTIONAL: The verification method that Google used to verify the phone number.

VerificationMethod

Enums
UNKNOWN_VERIFICATION_METHOD Do not ever set this default value!
CARRIER_API Google verified the user's phone number via a direct API call to a mobile carrier-owned API.
SMS_MT_GOOGLE_ORIGINATED Google verified the user's phone number by sending an SMS to the phone (a.k.a. mobile terminated SMS, or SMS-MT) and collecting/verifying the SMS programmatically.
SMS_MO_GOOGLE_TERMINATED Google verified the user's phone number by triggering a mobile-originating SMS (a.k.a. SMS-MO) to a Google-owned SMS gateway.

AuthenticateIdentityResponse

Response object for the authenticate identity method.

JSON representation 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "paymentIntegratorAuthenticateIdentityId": string,
  "result": enum (AuthenticateIdentityResultCode)
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
paymentIntegratorAuthenticateIdentityId

string

OPTIONAL: This identifier is specific to the integrator and is generated by the integrator. It is used for debugging purposes only in order to identify this call. This is the identifier that the integrator knows this call by.
result

enum (AuthenticateIdentityResultCode)

REQUIRED: Result of the authenticate identity call.

AuthenticateIdentityResultCode

Result codes for authenticate identity.

Enums
UNKNOWN_RESULT Do not ever set this default value!
SUCCESS The user has been successfully authenticated.
ADDITIONAL_USER_AUTHENTICATION_NEEDED

The user must complete an authentication flow with the integrator. The authentication will be initiated with the same requestId that was used in this call's requestHeader.

The specific authentiation method used will be chosen by Google from the set of remaining authentication methods that are valid for the user's current context. For instance, if the payment integrator has support for the SMS-MT OTP Authentication and the Web Redirect flows, Google might choose to send the user through the SMS-MT OTP Flow in order to authenticate the user. If the user is not on their mobile phone at the time of authenticating, Google might choose to send them through the Web Redirect Authentication Flow instead.

If no additional authentication flows are available, the overall authentication will fail.