Method: associateAccount

Page Summary

The Associate Account API enables payment processors to link a customer's account with a Google payment instrument using a GooglePaymentToken and associationId for authentication and payments.
The request includes a GooglePaymentToken, associationId, authenticationRequestId, and user information (optional), sent securely via a server-to-server call.
A successful response provides details about the associated account, such as transaction limits, account identifiers, and potentially user information, while errors are indicated by specific result types or HTTP error codes.
GooglePaymentToken contains an issuerId and token, crucial for identifying and processing payments linked to the user's account.
The API supports idempotency using a combination of requestId and paymentIntegratorAccountId, preventing duplicate association attempts.

HTTP request
Request body
- JSON representation
Response body
GooglePaymentToken
- JSON representation
IssuerId
- JSON representation
AssociateAccountResponse
- JSON representation
AssociateAccountResult
- JSON representation
SuccessDetails
- JSON representation
UserInformation
- JSON representation

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 through 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. The GPT is used to initiate payments.

The requestId within the header is the idempotency key and uniquely identifies this association attempt.

If Google sends an associationId or a googlePaymentToken that the integrator has already seen during a different association attempt (different idempotency key), the expectation is this would throw an HTTP 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": 2
    },
    "requestId": "cmVxdWVzdDE",
    "requestTimestamp": {
      "epochMillis": "1481899949606"
    },
    "paymentIntegratorAccountId": "InvisiCashUSA_USD"
 },
  "googlePaymentToken": {
    "issuerId": {
      "value": "InvisiCashUSA"
    },
    "token": "ZXhhbXBsZSB1bmlxdWUgcGF5bWVudCB0b2tlbiB2YWx1ZQ"
  },
 "authenticationRequestId": "bnAxdWTydDX==",
 "associationId": "LmddbXBsZSByZWZlcmVuY2UgdG9rZW4gdmFsdWU_",
 "provideUserInformation": true
}

An example response looks like:


  {
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": "1481899949611"
    }
  },
  "result": {
    "success": {
      "transactionLimits": {
        "transactionMaxLimit": {
          "limitAmount": {
            "amountMicros": "100000000",
            "currencyCode": "JPY"
          }
        }
      },
      "associatedAccountIdentifier": {
        "accountId": "1234-5678-91"
      },
      "associatedAccountDetails": {
        "accountNickname" : {
          "partialAccountNickname": "***-91"
        },
        "accountAlias": {
          "phoneNumber": {
            "value": "+15555555555"
          }
        }
      },
      "userInformation": {
        "name": "Example Customer",
        "addressLine": ["123 Main St"],
        "localityName": "Springfield",
        "administrativeAreaName": "CO",
        "postalCodeNumber": "80309",
        "countryCode": "US"
      }
    }
  }
}

HTTP request

POST https://www.integratorhost.example.com/integrator-base-path/v2/associateAccount

Request body

The request body contains data with the following structure:

JSON representation

JSON representation
{ "requestHeader": { object (`RequestHeader`) }, "provideUserInformation": boolean, "googlePaymentToken": { object (`GooglePaymentToken`) }, "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 // End of mutually exclusive fields. }

{
  "requestHeader": {
    object (RequestHeader)
  },
  "provideUserInformation": boolean,
  "googlePaymentToken": {
    object (GooglePaymentToken)
  },
  "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
  // End of mutually exclusive fields.
}

Fields
`requestHeader`	`object (RequestHeader)` REQUIRED: Common header for all requests.
`provideUserInformation`	`boolean` REQUIRED: True if we want the integrator to provide the address associated with this account.
`googlePaymentToken`	`object (GooglePaymentToken)` REQUIRED: The token that Google will use to initiate purchases with the payment processor.
`associationId`	`string` REQUIRED: The identifier of this association, created by Google. 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` `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`.
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.

Possible response messages
HTTP 200 Status	`object (AssociateAccountResponse)`
HTTP 4XX / 5XX Status	`object (ErrorResponse)`
End of mutually exclusive fields.

GooglePaymentToken

Describes a GooglePaymentToken (GPT), including the token and the issuer of the backing user account.

JSON representation
{ "issuerId": { object (`IssuerId`) }, "token": string }

Fields

Fields
`issuerId`	`object (IssuerId)` REQUIRED: The identifier of the issuer of the backing user account.
`token`	`string` REQUIRED: This is the token that both companies will use to identify the account for purchases between each other.

issuerId

object (IssuerId)

REQUIRED: The identifier of the issuer of the backing user account.

token

string

REQUIRED: This is the token that both companies will use to identify the account for purchases between each other.

IssuerId

A unique identifier for an issuer of user accounts.

JSON representation
{ "value": string }

Fields

Fields
`value`	`string` REQUIRED: The string value of the identifier. This unique identifier is defined by Google. Google will share a list with the identifiers for all external issuers available through the payment integrator.

value

string

REQUIRED: The string value of the identifier. This unique identifier is defined by Google. Google will share a list with the identifiers for all external issuers available through the payment integrator.

AssociateAccountResponse

Response object for the associate account method.

JSON representation
{ "responseHeader": { object (`ResponseHeader`) }, "result": { object (`AssociateAccountResult`) } }

Fields

Fields
`responseHeader`	`object (ResponseHeader)` REQUIRED: Common header for all responses.
`result`	`object (AssociateAccountResult)` REQUIRED: Result of this association.

responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.

result

object (AssociateAccountResult)

REQUIRED: Result of this association.

AssociateAccountResult

The result of the account association.

JSON representation

JSON representation
{ // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "success": { object (`SuccessDetails`) }, "userAuthenticationFailed": { object (`Empty`) }, "notEligible": { object (`Empty`) }, "otpNotMatched": { object (`Empty`) }, "otpAlreadyUsed": { object (`Empty`) }, "otpLimitReached": { object (`Empty`) } // End of mutually exclusive fields. }

{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "success": {
    object (SuccessDetails)
  },
  "userAuthenticationFailed": {
    object (Empty)
  },
  "notEligible": {
    object (Empty)
  },
  "otpNotMatched": {
    object (Empty)
  },
  "otpAlreadyUsed": {
    object (Empty)
  },
  "otpLimitReached": {
    object (Empty)
  }
  // End of mutually exclusive fields.
}

Fields
REQUIRED: The result of the account association. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
`success`	`object (SuccessDetails)` The account association was successful.
`userAuthenticationFailed`	`object (Empty)` Even though the account authentication bundle was returned, the user authentication failed.
`notEligible`	`object (Empty)` User's account is not eligible for this service.
`otpNotMatched`	`object (Empty)` OTP did not match what the integrator sent.
`otpAlreadyUsed`	`object (Empty)` OTP was already used.
`otpLimitReached`	`object (Empty)` User has requested or tried to verify too many OTPs.
End of mutually exclusive fields.

SuccessDetails

Details about a successful account association.

JSON representation

JSON representation
{ "transactionLimits": { object (`TransactionLimits`) }, "userInformation": { object (`UserInformation`) }, // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "associatedAccountIdentifier": { object (`AssociatedAccountIdentifier`) }, "bankAccountIdentifier": { object (`BankAccountIdentifier`) } // End of mutually exclusive fields. // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "associatedAccountDetails": { object (`AssociatedAccountDetails`) }, "bankAccountDetails": { object (`MaskedBankAccountDetails`) } // End of mutually exclusive fields. }

{
  "transactionLimits": {
    object (TransactionLimits)
  },
  "userInformation": {
    object (UserInformation)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "associatedAccountIdentifier": {
    object (AssociatedAccountIdentifier)
  },
  "bankAccountIdentifier": {
    object (BankAccountIdentifier)
  }
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "associatedAccountDetails": {
    object (AssociatedAccountDetails)
  },
  "bankAccountDetails": {
    object (MaskedBankAccountDetails)
  }
  // End of mutually exclusive fields.
}

Fields
`transactionLimits`	`object (TransactionLimits)` REQUIRED: Defines user scoped transaction limits.
`userInformation`	`object (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.
REQUIRED: The account ID the user has with the financial institution. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
`associatedAccountIdentifier`	`object (AssociatedAccountIdentifier)` The account ID the user has with the integrator.
`bankAccountIdentifier`	`object (BankAccountIdentifier)` The account ID the user has with a bank.
End of mutually exclusive fields.
REQUIRED: Details about the account that was associated. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
`associatedAccountDetails`	`object (AssociatedAccountDetails)` Details about the account that was associated.
`bankAccountDetails`	`object (MaskedBankAccountDetails)` Details about the bank account that was associated.
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.

Method: associateAccount Stay organized with collections Save and categorize content based on your preferences.

Page Summary

HTTP request

Request body

Response body

GooglePaymentToken

IssuerId

AssociateAccountResponse

AssociateAccountResult

SuccessDetails

UserInformation

Method: associateAccount