Method: linkUserAccount

Links a Google User account to a Partner (Payment Integrator) User account.

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
    },
    "requestId": "qierozie12345",
    "requestTimestamp": {
      "epochMillis": "1481899949606"
    },
    "paymentIntegratorAccountId": "GoldenPartner123"
  },
  "authenticationRequestId": "randomAuthRequestId123",
  "aggregatorAccountLinkingId": "randomAggregatorAccountLinkingId123",
  "riskSignals": {
    "googleAccountId": "1b1481aabac2cbecb76a47f2f07813ee9c961b78653d3938e61f5efcbc47e162"
  },
  "userDetails": {
    "maskedEmailAddress": "l***r@gmail.com"
  }
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": "1481899949611"
    }
  },
  "result": {
    "success": {
      "partnerAccountId": "60b71a178dbade80",
      "partnerAccountDisplayName": "+1 ***-***-1234"
    }
  }
}

HTTP request

POST https://www.integratorhost.example.com/integrator-base-path/partner-user-account-linking-v1/linkUserAccount

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "authenticationRequestId": string,
  "aggregatorAccountLinkingId": string,
  "riskSignals": {
    object (RiskSignals)
  },
  "userDetails": {
    object (UserDetails)
  }
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.

This header contains the requestId which is known as the LinkUserAccountRequestId in other methods. It will be used in subsequent calls as a reference to the linkUserAccount request that linked the user's accounts.

If user accounts are linked, unlinked, then linked again, the new linkUserAccount request will have a new requestId.
authenticationRequestId

string

REQUIRED: The requestId of the AuthenticationRequest/Response in the Authentication flow.

This is a string that has a max length of 100 characters, and contains only the characters "a-z", "A-Z", "0-9", ":", "-", and "_".
aggregatorAccountLinkingId

string

OPTIONAL: An extra account linking ID that will only be generated for Partners that have an Aggregator between Google and the Partner for 1P e-Wallet payments. The purpose is to keep the real requestId private from the Aggregator.

When Google calls the e-Wallet FOP associateAccount method at the Aggregator, Google will pass this ID to the Aggregator instead of the authenticationRequestId because the authentication step was completed by this partner-user-account-linking-v1.linkUserAccount call.

This is a string that has a max length of 100 characters, and contains only the characters "a-z", "A-Z", "0-9", ":", "-", and "_".
riskSignals

object (RiskSignals)

REQUIRED: The risk signals used by the Partner to make a risk assessment about linking the two accounts.
userDetails

object (UserDetails)

REQUIRED: Details about the user.

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

object (ErrorResponse)

RiskSignals

The risk signals used by the Partner to make a risk assessment about linking the two accounts.

JSON representation 
{
  "googleAccountId": string
}
Fields
googleAccountId

string

REQUIRED: A unique identifier representing the Google user's account. This is stable for the same Google account across multiple link user account requests, e.g. If the user links, unlinks, then links again, or re-links under different Payment Profiles, this ID will stay the same. The value for a given Google account will be different for different partners.

This is a string that has a max length of 100 characters, and contains only the characters "a-z", "A-Z", "0-9", ":", "-", and "_".

UserDetails

Details about the user.

JSON representation 
{
  "maskedEmailAddress": string
}
Fields
maskedEmailAddress

string

REQUIRED: The masked email address of the Google account. Used in the Partner's ecosystem to indicate to a user which accounts have been linked. 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.

LinkUserAccountResponse

Response object for the linkUserAccount method.

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

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

object (LinkUserAccountResult)

REQUIRED: Contains the result of the request.

LinkUserAccountResult

Details corresponding to the result.

JSON representation 
{

  // Union field result can be only one of the following:
  "success": {
    object (LinkUserAccountSuccessResult)
  },
  "accountLinkLimitExceeded": {
    object (Empty)
  }
  // End of list of possible types for union field result.
}
Fields
Union field result. REQUIRED: Contains the possible result types. Exactly one must be set. result can be only one of the following:
success

object (LinkUserAccountSuccessResult)

The request to link user accounts was successful.

LinkUserAccountSuccessResult

Details about the success result.

JSON representation 
{
  "partnerAccountId": string,
  "partnerAccountDisplayName": string,
  "listPaymentMethodsSuccessResult": {
    object (ListPaymentMethodsSuccessResult)
  }
}
Fields
partnerAccountId

string

REQUIRED: The account ID the user has with the Partner. This is used for Google risk to understand account re-use, account relationships, and de-duplication. It is also used for Google customer operation agents to help users diagnose issues. It must NOT contain Sensitive Personally Identifiable Information and is NOT treated as a sensitive ID.

This value must be immutable for the life of the account.
partnerAccountDisplayName

string

REQUIRED: A human-readable display name for the account. This will be displayed to the user as-is on Google surfaces, e.g. to show what partner account has been linked. For example, it could be an account number also found on the user's account statement, a phone number, or an email address. It can also be either full or masked.

It is NOT treated as a sensitive ID and must NOT contain SPII (Sensitive Personally Identifiable Information). For example, sensitive national ID numbers or financial account IDs that can be used to make purchases.

Example using a masked phone number: "+1 ***-***-1234"
listPaymentMethodsSuccessResult

object (ListPaymentMethodsSuccessResult)

OPTIONAL: The list of payment methods contained within the Partner user's account.

Typically, a successful account linking would be followed up with a call to listPaymentMethods. If the integrator pre-emptively embeds the result for that call here, Google can use it to skip the call to listPaymentMethods entirely. This is an optimization to reduce the user-perceived latency of the account linking process.