Method: associateAccount

將客戶帳戶與付款處理方的關聯，連結至要新增的 Google 付款方式。

整合商驗證使用者後，帳戶就會建立關聯。關聯是透過伺服器對伺服器呼叫進行，該呼叫包含相關聯驗證流程 (authenticationRequestId)、associationId 和 googlePaymentToken (GPT) 的 requestId。付款處理方應將 associationId 和 googlePaymentToken 連結至客戶的帳戶，以便進行驗證。GPT 是用來辦理付款。在重新驗證呼叫期間，系統會使用 associationId 來識別要驗證的帳戶。

如果 Google 傳送 associationId 或 googlePaymentToken，且整合商在其他關聯中已看過，就會擲回錯誤。

如果端點在處理要求時發生錯誤，來自這個端點的回應主體應為 ErrorResponse 類型。

要求範例如下：


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "cmVxdWVzdDE",
    "requestTimestamp": "1481899949606"
 },
 "googlePaymentToken": "ZXhhbXBsZSB1bmlxdWUgcGF5bWVudCB0b2tlbiB2YWx1ZQ__",
 "authenticationRequestId": "bnAxdWTydDX==",
 "associationId": "LmddbXBsZSByZWZlcmVuY2UgdG9rZW4gdmFsdWU_",
 "provideUserInformation": true
}

回應範例如下所示：


  {
  "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 要求

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

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "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.
}
欄位
requestHeader

object (RequestHeader)

必要項目：所有要求的通用標頭。
provideUserInformation

boolean

必要項目：如果我們要求整合者提供與此帳戶相關聯的地址，則為 True。
googlePaymentToken

string

必要項目：Google 將用於透過付款處理方發起交易的權杖。

這個字串的長度上限為 100 個半形字元。
associationId

string

必要項目：此關聯的 ID。這個 ID 是由 Google 建立，會在重新驗證流程期間傳送，用來識別應驗證的帳戶。

這個字串的長度上限為 100 個半形字元。

聯集欄位 account_verification。

account_verification 只能採用下列其中一種設定：
authenticationRequestId

string

OPTIONAL：引發此呼叫前的驗證要求 requestId。這個 ID 是由 Google 在驗證流程中產生。只有在使用者採用 Android 應用程式驗證、網路驗證或採用 authenticationResultNotification 的非同步驗證方法時，才會出現這種情況。
otpVerification

object (OtpVerification)

選用：驗證 sendOtp 產生的動態密碼所需的資料。只有在使用者經過 sendOtp 路徑時，系統才會顯示這個項目。

回應主體

助理帳戶方法的回應物件。

如果成功，回應主體會含有以下結構的資料：

JSON 表示法 
{
  "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.
}
欄位
responseHeader

object (ResponseHeader)

必要項目：所有回應的通用標頭。
paymentIntegratorAssociateAccountId

string

必要項目：此 ID 專屬於整合商，由整合商產生。只會將其用於偵錯，以便辨識這個呼叫。這是整合商瞭解此呼叫的 ID。
tokenExpirationTime

string (int64 format)

選用：權杖到期後經過的毫秒數。使用 0 表示權杖不會過期。
accountId

string

必要項目：整合商的使用者帳戶 ID。這項資訊可讓 Google 風險瞭解重複利用帳戶、帳戶關係，以及 Google 客戶業務專員，協助客戶診斷問題。這個 ID 必須可供使用者識別 (例如：使用者知道這個 ID，因為這項資訊會顯示在對帳單中，或是在登入帳戶後顯示在網站上)。

在帳戶效期內，這個值不得變動。
userMessage
(deprecated)

string

已淘汰：在結果不是 SUCCESS 時，要向使用者顯示的結果說明。
userInformation

object (UserInformation)

必要項目：整合商已知悉的使用者資訊，並將該客戶提供給 Google，用於風險資訊並解決預先填入問題。
result

enum (AssociateAccountResultCode)

必要項目：此關聯的結果。

聯集欄位 account_names。

account_names 只能採用下列其中一種設定：
accountNickname

string

選用：使用者已知此帳戶的字串，以供顯示。這是帳戶暱稱的後置字元。例如，電話號碼末 4 碼。Google 會在使用者介面中指出這只是暱稱的後置字串。

這個值會顯示在購買流程等使用者介面中，方便使用者分辨付款方式。
fullAccountNickname

string

選用：使用者已知此帳戶的字串，以供顯示。與 accountNickname 不同，這是完整帳戶暱稱。例如 56565-56501 代表電話號碼，或 sally@sample-email.com 代表電子郵件身分。

這個值會顯示在購買流程等使用者介面中，方便使用者分辨付款方式。

UserInformation

可保存使用者資訊的結構。

JSON 表示法 
{
  "name": string,
  "addressLine": [
    string
  ],
  "localityName": string,
  "administrativeAreaName": string,
  "postalCodeNumber": string,
  "countryCode": string,
  "phone": string,
  "emailAddress": string
}
欄位
name

string

選用：客戶的全名。
addressLine[]

string

選用：包含非結構化的地址文字。
localityName

string

選用：這是模糊的字詞，但通常是指地址的縣市/鄉鎮部分。如為未明確定義縣市或不適用於該結構的區域 (例如日本和中國)，請將 localityName 留白並使用 addressLine。

範例：美國城市、義大利市鎮、英國郵鎮。
administrativeAreaName

string

選用：這個國家/地區的頂層行政劃分」例如：美國各州、義大利地區、中國省份、日本的都/道/府/縣。」
postalCodeNumber

string

選用：儘管名稱已開放，postalCodeNumber 值經常是英數字元。例如：「94043」、「SW1W」、「SW1W 9TQ」。
countryCode

string

選用：客戶地址的國家/地區代碼，應為 ISO-3166-1 Alpha-2。
phone

string

選用：客戶的電話號碼。
emailAddress

string

選用：客戶的電子郵件地址。

AssociateAccountResultCode

關聯帳戶的結果代碼。

列舉
UNKNOWN_RESULT 切勿設定這個預設值！
SUCCESS 成功連結。
USER_AUTHENTICATION_FAILED 即使已傳回帳戶驗證組合，使用者驗證失敗。
NOT_ELIGIBLE 使用者帳戶無法使用這項服務。
OTP_NOT_MATCHED 動態密碼與整合服務供應商傳送的資料不符。
OTP_ALREADY_USED 動態密碼已有人使用。
OTP_LIMIT_REACHED 使用者要求或嘗試驗證的動態密碼過多。
OTP_EXPIRED 動態密碼已失效。