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 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 for authentication. The GPT is used to initiate payments. The associationId is used during re-authentication calls to identify the account for authentication.

The combination of requestId within the header and paymentIntegratorAccountId 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": 1
    },
    "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/carriers-v1/associateAccount

Request body

The request body contains data with the following structure:

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

  // Union field account_verification can be only one of the following:
  "authenticationRequestId": string
  // 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 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. 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

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.

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)

AssociateAccountResponse

Response object for the associate account method.

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

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

object (AssociateAccountResult)

REQUIRED: Result of this association.

AssociateAccountResult

JSON representation 
{

  // Union field result can be only one of the following:
  "success": {
    object (SuccessDetails)
  },
  "userAuthenticationFailed": {
    object (Empty)
  },
  "notEligible": {
    object (Empty)
  },
  "otpNotMatched": {
    object (Empty)
  },
  "otpAlreadyUsed": {
    object (Empty)
  },
  "otpLimitReached": {
    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 (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.

SuccessDetails

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

  // Union field account_identifier can be only one of the following:
  "associatedAccountIdentifier": {
    object (AssociatedAccountIdentifier)
  },
  "bankAccountIdentifier": {
    object (BankAccountIdentifier)
  }
  // End of list of possible types for union field account_identifier.

  // Union field account_details can be only one of the following:
  "associatedAccountDetails": {
    object (AssociatedAccountDetails)
  },
  "bankAccountDetails": {
    object (MaskedBankAccountDetails)
  }
  // End of list of possible types for union field account_details.
}
Fields
transactionLimits

object (TransactionLimits)

REQUIRED: Defines user scoped transaction limits.
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.

Union field account_identifier.

account_identifier can be only one of the following:
associatedAccountIdentifier

object (AssociatedAccountIdentifier)

The account ID the user has with the integrator.
bankAccountIdentifier

object (BankAccountIdentifier)

The account ID the user has with a bank.

Union field account_details.

account_details can be only one of the following:
associatedAccountDetails

object (AssociatedAccountDetails)

Details about the account that was associated.
bankAccountDetails

object (MaskedBankAccountDetails)

Details about the bank account that was associated.

AssociatedAccountIdentifier

JSON representation 
{
  "accountId": string
}
Fields
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 value must be immutable for the life of the account.

BankAccountIdentifier

Unique identifier of a bank account.

JSON representation 
{

  // Union field account_identifier can be only one of the following:
  "singaporeBankAccount": {
    object (SgBankAccount)
  },
  "usBankAccount": {
    object (UsBankAccount)
  },
  "japanBankAccount": {
    object (JapanBankAccount)
  }
  // End of list of possible types for union field account_identifier.
}
Fields

Union field account_identifier.

account_identifier can be only one of the following:
singaporeBankAccount

object (SgBankAccount)

An account with a bank in Singapore.
usBankAccount

object (UsBankAccount)

An account with a bank in the United States.
japanBankAccount

object (JapanBankAccount)

An account with a bank in Japan.

SgBankAccount

Details of a user's bank account in SG.

JSON representation 
{
  "sgFastBankAccount": {
    object (SgFastBankAccount)
  },
  "localBankIdentifier": {
    object (SgLocalBankIdentifier)
  }
}
Fields
sgFastBankAccount

object (SgFastBankAccount)

FAST-related bank account details.
localBankIdentifier

object (SgLocalBankIdentifier)

Bank Id with local identifiers.

SgFastBankAccount

Details of a customer's bank account in SG that are relevant for operations that involve the FAST payment network.

JSON representation 
{
  "localAccountNumber": string,
  "swiftBic": {
    object (SwiftBusinessIdentifierCode)
  }
}
Fields
localAccountNumber

string

The local account number for this account.
swiftBic

object (SwiftBusinessIdentifierCode)

SWIFT Business Identifier Code as defined in ISO 9362.

SwiftBusinessIdentifierCode

SWIFT Business Identifier Code as defined in ISO 9362.

JSON representation 
{
  "value": string
}
Fields
value

string

An 8-character code, defined as 'business party identifier', consisting of the business party prefix (4 alphanumeric), the country code as defnied in ISO 3166-1 (2 alphabetic), and the business party suffix (2 alphanumeric). The branch identifier is a 3-character optional element that can supplement the 8-character BIC, used to identify specific location, departments, services or units of the same business party.

SgLocalBankIdentifier

Local Ids for a bank in Singapore.

JSON representation 
{
  "localBankCode": string,
  "localBranchCode": string
}
Fields
localBankCode

string

Bank code of the customer bank.
localBranchCode

string

Code of the branch where the customer account is located.

UsBankAccount

Details of a user's bank account in the US.

JSON representation 
{
  "accountNumber": {
    object (DomesticBankAccountNumber)
  },
  "bankIdentifier": {
    object (UsBankIdentifier)
  }
}
Fields
accountNumber

object (DomesticBankAccountNumber)

Account number for the bank account.
bankIdentifier

object (UsBankIdentifier)

Globally identifies the bank where this account is held.

DomesticBankAccountNumber

Local representation of a bank account number for domestic transfers.

JSON representation 
{
  "number": string
}
Fields
number

string

The local bank account number.

UsBankIdentifier

Identifiers for a Bank in the United States.

JSON representation 
{
  "swiftBic": {
    object (SwiftBusinessIdentifierCode)
  },
  "usAbaRoutingNumber": {
    object (AbaRoutingTransitNumber)
  }
}
Fields
swiftBic

object (SwiftBusinessIdentifierCode)

SWIFT Business Identifier Code as defined in ISO 9362.
usAbaRoutingNumber

object (AbaRoutingTransitNumber)

US ABA routing number (ABA RTN).

AbaRoutingTransitNumber

An American Bankers Association (ABA) routing transit number (ABA RTN).

JSON representation 
{
  "value": string
}
Fields
value

string

ABA routing transit number.

JapanBankAccount

Details of a user's bank account in Japan.

JSON representation 
{
  "localAccountNumber": string,
  "localBankIdentifier": {
    object (JapanLocalBankIdentifier)
  }
}
Fields
localAccountNumber

string

Local account number for the bank account.
localBankIdentifier

object (JapanLocalBankIdentifier)

Bank ID with local identifiers.

JapanLocalBankIdentifier

Local IDs for a bank in Japan.

JSON representation 
{
  "localBankCode": string,
  "localBranchCode": string
}
Fields
localBankCode

string

Bank code of the customer bank.
localBranchCode

string

Code of the branch where the customer account is located.

AssociatedAccountDetails

JSON representation 
{
  "accountNickname": {
    object (AssociatedAccountNickname)
  },
  "accountAlias": {
    object (AccountAlias)
  },
  "accountType": {
    object (AccountType)
  }
}
Fields
accountNickname

object (AssociatedAccountNickname)

Nickname by which the user knows this account for display purposes.
accountAlias

object (AccountAlias)

OPTIONAL: An additional account alias the user might use to identify their vendor account. These are used by Google customer operation agents to help customers diagnose issues. These aliases should be user recognizable (for example the user knows this alias because it appears on their statement or appears on the website after they log into the account).
accountType

object (AccountType)

OPTIONAL: Account type information that will be used to tailor display messages to users. For example, this could contain information about the payment plan the user has with the integrator for this account.

AssociatedAccountNickname

JSON representation 
{

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

Union field account_names.

account_names can be only one of the following:
partialAccountNickname

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.

This value will be displayed in UIs like the purchase flow to allow the user to distinguish between payment methods.
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 for an email identity.

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

AccountAlias

Defines the type and value of an alias that a user associates with their vendor account.

JSON representation 
{

  // Union field account_alias can be only one of the following:
  "phoneNumber": {
    object (PhoneNumber)
  },
  "emailAddress": string
  // End of list of possible types for union field account_alias.
}
Fields
Union field account_alias. REQUIRED: An account alias the user has with the integrator. account_alias can be only one of the following:
phoneNumber

object (PhoneNumber)

The phone number the user has on file with the integrator.
emailAddress

string

The email address the user has on file with the integrator.

AccountType

JSON representation 
{

  // Union field account_type can be only one of the following:
  "wirelessCarrierAccountType": {
    object (WirelessCarrierAccountType)
  }
  // End of list of possible types for union field account_type.
}
Fields

Union field account_type.

account_type can be only one of the following:
wirelessCarrierAccountType

object (WirelessCarrierAccountType)

WirelessCarrierAccountType

The account type the user has with a wireless carrier. This is used to tailor display messages to the users. For example, the payment dialog for a user with a prepaid plan may say "deduct from your carrier balance", rather than "bill to your carrier account."

JSON representation 
{

  // Union field carrier_account_type can be only one of the following:
  "prepaid": {
    object (Empty)
  },
  "postpaid": {
    object (Empty)
  },
  "enterprise": {
    object (Empty)
  },
  "willNotProvidePii": {
    object (Empty)
  },
  "controlPlan": {
    object (Empty)
  }
  // End of list of possible types for union field carrier_account_type.
}
Fields

Union field carrier_account_type.

carrier_account_type can be only one of the following:
prepaid

object (Empty)

Indicates the user is on a prepaid payment plan with their wireless carrier (e.g. the user pays for the coming month). Payments made with this account will be deducted from the prepaid balance.
postpaid

object (Empty)

Indicates the user is on a postpaid payment plan with their wireless carrier (e.g. the user pays for the prior month). Payments made with this account will accrue until the balance is paid off.
enterprise

object (Empty)

Indicates the user is part of an enterprise wireless plan (e.g. the user is on a shared corporate phone plan).
willNotProvidePii

object (Empty)

Indicates the carrier will not provide this information because a user's payment plan is considered PII, or because the carrier is otherwise legally obligated not to share this information.
controlPlan

object (Empty)

Indicates the user is on a control plan with their wireless carrier. This could be a payment plan where the user pays the same monthly fee, and calls or charges made against by the user are debited from this monthly fee. Once the monthly fee amount is exhausted, certain services are limited or disabled unless the user makes a mid-cycle payment to re-enable these services.

MaskedBankAccountDetails

Masked account details of a bank account.

JSON representation 
{
  "accountNumberSuffix": string,
  "bankAccountType": {
    object (BankAccountType)
  },
  "bankAccountMetadata": {
    object (BankAccountMetadata)
  }
}
Fields
accountNumberSuffix

string

Suffix of the account number.
bankAccountType

object (BankAccountType)

Account type of the bank account.
bankAccountMetadata

object (BankAccountMetadata)

Metadata about this account.

BankAccountType

Account type of a bank account.

JSON representation 
{
  "type": enum (Type)
}
Fields
type

enum (Type)

Type

Enums
TYPE_UNSPECIFIED Do not ever set this default value!
SAVINGS
CHECKING
CURRENT

BankAccountMetadata

Metadata about the bank account.

JSON representation 
{
  "bankingProductName": string
}
Fields
bankingProductName

string

The banking product name of this account.

TransactionLimits

Defines transaction limits for the enclosing entity.

JSON representation 
{
  "transactionMaxLimit": {
    object (TransactionLimit)
  }
}
Fields
transactionMaxLimit

object (TransactionLimit)

REQUIRED: Defines the value and currency of a maximum per transaction limit for the enclosing type, or states that no maximum per transaction limit exists.

TransactionLimit

Defines a transaction limit amount or the absence of a limit.

JSON representation 
{

  // Union field transaction_limit can be only one of the following:
  "limitAmount": {
    object (Amount)
  },
  "noLimit": {
    object (Empty)
  }
  // End of list of possible types for union field transaction_limit.
}
Fields

Union field transaction_limit.

transaction_limit can be only one of the following:
limitAmount

object (Amount)

The value of the allowable transaction. This is used to determine whether or not the user should be given this integrator as an option to process a specific transaction.
noLimit

object (Empty)

Indicates that there is no transaction limit. This is used to determine whether or not the user should be given this integrator as an option to process a specific transaction.

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.