- [HTTP request](https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/associateAccount#body.HTTP_TEMPLATE)
- [Request body](https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/associateAccount#body.request_body)
  - [JSON representation](https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/associateAccount#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/associateAccount#body.response_body)
- [AssociateAccountResponse](https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/associateAccount#AssociateAccountResponse)
  - [JSON representation](https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/associateAccount#AssociateAccountResponse.SCHEMA_REPRESENTATION)
- [UserInformation](https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/associateAccount#UserInformation)
  - [JSON representation](https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/associateAccount#UserInformation.SCHEMA_REPRESENTATION)
- [AssociateAccountResultCode](https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/associateAccount#AssociateAccountResultCode)

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 `https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/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/integrator-base-path/e-wallets-v1/associateAccount`

### Request body

The request body contains data with the following structure:

| JSON representation |
|---|
| ``` { "requestHeader": { object (`https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/RequestHeader`) }, "provideUserInformation": boolean, "googlePaymentToken": string, "associationId": string, // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "authenticationRequestId": string, "otpVerification": { object (`https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/OtpVerification`) }, "aggregatorAccountLinkingId": string // End of mutually exclusive fields. } ``` |

| Fields ||
|---|---|
| `requestHeader` | ``object (`https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/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. |
| **REQUIRED**: The method used to verify the user's account. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: ||
| `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 (`https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/OtpVerification`)`` **OPTIONAL** : Data necessary to verify an OTP generated from `sendOtp`. This is only present if the user went through the `sendOtp` path. |
| `aggregatorAccountLinkingId` | `string` **OPTIONAL** : An ID representing an earlier Partner User Account Linking via `LinkUserAccount` action that linked the user's accounts. The ID is known to Google, the Partner (i.e. Account Issuer), and the Partner's aggregator (i.e. Payment Integrator). This ID will be passed to the Partner's aggregator instead of the `authenticationRequestId` because the authentication step was completed by the `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 "_". |
| End of mutually exclusive fields. ||

### 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](https://developers.google.com/pay/e-wallets-v1/guides/connectivity/protocol-standards#http_status_codes).

| Possible response messages ||
|---|---|
| HTTP 200 Status | ``object (`https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/associateAccount#AssociateAccountResponse`)`` |
| HTTP 4XX / 5XX Status | ``object (`https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/ErrorResponse`)`` |
| End of mutually exclusive fields. ||

## AssociateAccountResponse

Response object for the associate account method.

| JSON representation |
|---|
| ``` { "responseHeader": { object (`https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/ResponseHeader`) }, "paymentIntegratorAssociateAccountId": string, "tokenExpirationTime": string, "accountId": string, "userMessage": string, "userInformation": { object (`https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/associateAccount#UserInformation`) }, "result": enum (`https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/associateAccount#AssociateAccountResultCode`), // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "accountNickname": string, "fullAccountNickname": string // End of mutually exclusive fields. } ``` |

| Fields ||
|---|---|
| `responseHeader` | ``object (`https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/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 (https://developers.google.com/discovery/v1/type-format 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` > [!WARNING] > This was never implemented and is being removed in future versions. This field is ignored. **DEPRECATED** : A description of the result to be displayed to the user if the result is not `SUCCESS`. |
| `userInformation` | ``object (`https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/associateAccount#UserInformation`)`` **OPTIONAL**: User information that the integrator knows and will share with Google about this customer. Used for risk information and address prepopulation. This value is required if the `provideUserInformation` field is set to `true` in the request. |
| `result` | ``enum (`https://developers.google.com/pay/e-wallets-v1/payment-integrator-e-wallets-api/associateAccount#AssociateAccountResultCode`)`` **REQUIRED**: Result of this association. |
| **OPTIONAL** : `account_names` is required if result is `ACCEPTED`. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: ||
| `accountNickname` | `string` 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. <br /> > [!CAUTION] > **Caution:** This value can be PII, but must never be SPII. <br /> This value will be displayed in UIs like the purchase flow to allow the user to distinguish between payment methods. <br /> > [!NOTE] > **Note:** that either this value or the `fullAccountNickname` must be present, never both. <br /> |
| `fullAccountNickname` | `string` 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](mailto:sally@sample-email.com) for an email identity. <br /> > [!CAUTION] > **Caution:** This value can be PII, but must never be SPII. <br /> This value will be displayed in UIs like the purchase flow to allow the user to distinguish between payment methods. <br /> > [!NOTE] > **Note:** that either this value or the `accountNickname` must be present, never both. <br /> |
| End of mutually exclusive fields. ||

## 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. |