Method: associateAccount

Associates the customer's account with the payment processor to the Google instrument being added.

Account association happens after the integrator has authenticated the user. Association occurs via a server-to-server call that contains the requestId for the associated authentication flow (authenticationRequestId), an associationId and a googlePaymentToken (GPT). The payment processor should associate the associationId and the googlePaymentToken to the customer's account for authentication. The GPT is used to initiate payments. The associationId is used during re-authentication calls to identify the account for authentication.

If Google sends an associationId or a googlePaymentToken that the integrator has already seen during a different association, then it throws an error.

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": 0,
      "revision": 0
    },
    "requestId": "cmVxdWVzdDE",
    "requestTimestamp": "1481899949606"
 },
 "googlePaymentToken": "ZXhhbXBsZSB1bmlxdWUgcGF5bWVudCB0b2tlbiB2YWx1ZQ__",
 "authenticationRequestId": "bnAxdWTydDX==",
 "associationId": "LmddbXBsZSByZWZlcmVuY2UgdG9rZW4gdmFsdWU_",
 "provideUserInformation": true
}

An example response looks like:


  {
  "responseHeader": {
    "responseTimestamp": "1481899949611"
  },
  "paymentIntegratorAssociateAccountId": "xx77df88934hfd",
  "accountId": "1234-5678-91",
  "accountNickname": "***-91",
  "tokenExpirationTime": "0",
  "userInformation": {
    "name": "Example Customer",
    "addressLine": ["123 Main St"],
    "localityName": "Springfield",
    "administrativeAreaName": "CO",
    "postalCodeNumber": "80309",
    "countryCode": "US"
  },
  "result": "SUCCESS"
}

HTTP request

POST https://www.integratorhost.example.com/v1/associateAccount

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "provideUserInformation": boolean,
  "googlePaymentToken": string,
  "associationId": string,

  // Union field account_verification can be only one of the following:
  "authenticationRequestId": string,
  "otpVerification": {
    object (OtpVerification)
  }
  // End of list of possible types for union field account_verification.
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
provideUserInformation

boolean

REQUIRED: True if we desire the integrator to provide the address associated with this account.
googlePaymentToken

string

REQUIRED: The token that Google will use to initiate purchases with the payment processor.

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

string

REQUIRED: The identifier of this association. This identifier is created by Google and is sent during re-authentication flows to identify which account should be authenticated.

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

Union field account_verification.

account_verification can be only one of the following:
authenticationRequestId

string

OPTIONAL: requestId of the authentication request that preceded this call. This identifier was generated by Google during the authentication flow. This is only present if the user went through the Android app authentication, web authentication, or an asynchronous authentication method that uses authenticationResultNotification.
otpVerification

object (OtpVerification)

OPTIONAL: Data necessary to verify an OTP generated from sendOtp. This is only present if the user went through the sendOtp path.

Response body

Response object for the associate account method.

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

JSON representation 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "paymentIntegratorAssociateAccountId": string,
  "tokenExpirationTime": string,
  "accountId": string,
  "userMessage": string,
  "userInformation": {
    object (UserInformation)
  },
  "result": enum (AssociateAccountResultCode),

  // Union field account_names can be only one of the following:
  "accountNickname": string,
  "fullAccountNickname": string
  // End of list of possible types for union field account_names.
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
paymentIntegratorAssociateAccountId

string

REQUIRED: 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.
tokenExpirationTime

string (int64 format)

OPTIONAL: Milliseconds since epoch when the token expires. Use 0 to signal the token does not expire.
accountId

string

REQUIRED: The account ID the user has with the integrator. This is used for Google risk to understand account re-use and account relationships and Google customer operation agents to help customers diagnose issues. This identifier should be user recognizable (for example the user knows this ID because it appears on their statement or appears on the website after they log into the account).

This value must be immutable for the life of the account.
userMessage
(deprecated)

string

DEPRECATED: A description of the result to be displayed to the user if the result is not SUCCESS.
userInformation

object (UserInformation)

REQUIRED: User information that the integrator knows and will share with Google about this customer. Used for risk information and address prepopulation.
result

enum (AssociateAccountResultCode)

REQUIRED: Result of this association.

Union field account_names.

account_names can be only one of the following:
accountNickname

string

OPTIONAL: String by which the user knows this account for display purposes. This is a suffix of the account nickname. For example last four digits of a phone number. Google will indicate in the user interface that this is only a suffix of the nickname.

This value will be displayed in UIs like the purchase flow to allow the user to distinguish between payment methods.
fullAccountNickname

string

OPTIONAL: String by which the user knows this account for display purposes. Unlike accountNickname this is the full account nickname. For example 56565-56501 for a phone number or sally@sample-email.com for an email identity.

This value will be displayed in UIs like the purchase flow to allow the user to distinguish between payment methods.

UserInformation

Structure holding information about a user.

JSON representation 
{
  "name": string,
  "addressLine": [
    string
  ],
  "localityName": string,
  "administrativeAreaName": string,
  "postalCodeNumber": string,
  "countryCode": string,
  "phone": string,
  "emailAddress": string
}
Fields
name

string

OPTIONAL: Customer's full name.
addressLine[]

string

OPTIONAL: This holds unstructured Address text.
localityName

string

OPTIONAL: This is something of a fuzzy term, but it generally refers to the city/town portion of an address. In regions of the world where localities are not well defined or do not fit into this structure well (for example, Japan and China), leave localityName empty and use addressLine.

Examples: US city, IT comune, UK post town.
administrativeAreaName

string

OPTIONAL: Top-level administrative subdivision of this country" Examples: US state, IT region, CN province, JP prefecture."
postalCodeNumber

string

OPTIONAL: Despite the name, postalCodeNumber values are frequently alphanumeric. Examples: "94043", "SW1W", "SW1W 9TQ".
countryCode

string

OPTIONAL: Customer address country code, expected to be ISO-3166-1 Alpha-2.
phone

string

OPTIONAL: Customer's phone number.
emailAddress

string

OPTIONAL: Customer's email address.

AssociateAccountResultCode

Result codes for associate account.

Enums
UNKNOWN_RESULT Do not ever set this default value!
SUCCESS Successful association.
USER_AUTHENTICATION_FAILED Even though the account authentication bundle was returned, the user authentication failed.
NOT_ELIGIBLE User's account is not eligible for this service.
OTP_NOT_MATCHED OTP did not match what the integrator sent.
OTP_ALREADY_USED OTP was already used.
OTP_LIMIT_REACHED User has requested or tried to verify too many OTPs.
OTP_EXPIRED OTP has expired.