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.

An example request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 2
    },
    "requestId": "G112YZH4XPDV88J",
    "requestTimestamp": {
      "epochMillis": "1481907920000"
    },
    "paymentIntegratorAccountId": "InvisiCashUSA_USD"
  },
  "authenticationRequestId": "1591303-231233235-151J",
  "associationId": "15522364553"
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": "1502545413132"
    },
    "requestId": "G112YZH4XPDV88J"
  },
  "result": {
    "success": {}
  }
}

HTTP request

POST https://www.integratordomain.com/v2/authenticateIdentity

Request body

The request body contains data with the following structure:

JSON representation
{
  "requestHeader": {
    object (RequestHeader)
  },
  "authenticationRequestId": string,
  "associationId": string
}
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.

Response body

If successful, the response body contains data with the following structure:

Response object for the authenticate identity method.

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

object (ResponseHeader)

REQUIRED: Common header for all responses.

result

object (AuthenticateIdentityResult)

REQUIRED: Result of the authenticate identity call.

AuthenticateIdentityResult

Result codes for authenticate identity.

JSON representation
{

  // Union field result can be only one of the following:
  "success": {
    object (Empty)
  },
  "additionalUserAuthenticationNeeded": {
    object (Empty)
  }
  // End of list of possible types for union field result.
}
Fields

Union field result.

result can be only one of the following:

success

object (Empty)

The user has been successfully authenticated.

additionalUserAuthenticationNeeded

object (Empty)

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.