Method: associateAccount

• HTTP 要求
• 要求主體
  • JSON 表示法
• 回應主體
  • JSON 表示法
• UserInformation
  • JSON 表示法
• AssociateAccountResultCode

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

帳戶關聯作業會在整合商驗證使用者後開始。系統會透過伺服器對伺服器呼叫進行關聯，該呼叫包含相關聯驗證流程的 requestId (authenticationRequestId)、associationId 和 googlePaymentToken (GPT)。付款處理方應將 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) 選用：憑證到期後，從 Epoch 紀元時間起算，以秒為單位。使用 0 表示權杖不會過期。
accountId	string 必要項目：使用者擁有整合商的帳戶 ID。這些異動會用來瞭解 Google 風險，瞭解帳戶重複使用/帳戶之間的關係，以及 Google 客戶服務服務專員，協助客戶診斷問題。此 ID 必須是使用者可辨識的 (例如使用者知道這個 ID，因為這個 ID 顯示在自己的聲明中，或是在登入帳戶後顯示於網站上)。 這個值在帳戶效期內不得變更。
userMessage (deprecated)	string 目前從未實作過，將在日後的版本中移除。系統會忽略這個欄位。 已淘汰：如果結果不是 SUCCESS，要向使用者顯示的結果說明。
userInformation	object (UserInformation) 必要項目：整合商瞭解並與 Google 分享有關這位客戶的使用者資訊。用於風險資訊及處理預先填入。
result	enum (AssociateAccountResultCode) 必要項目：此關聯的結果。
聯集欄位 account_names。 account_names 只能採用下列其中一種設定：
accountNickname	string 選用：使用者知道這個帳戶做為顯示用途的字串。這是帳戶暱稱的後置字串。例如電話號碼的末 4 碼。Google 會在使用者介面中指出，這只是暱稱的後置字元。 注意：這個值可以是個人識別資訊，但一律不得含有 SPII。 這個值會顯示在購買流程等使用者介面中，方便使用者分辨付款方式。 注意：此值或 fullAccountNickname 必須存在，不能兩者都存在。
fullAccountNickname	string 選用：使用者知道這個帳戶做為顯示用途的字串。與 accountNickname 不同，這是完整的帳戶暱稱。例如，電話號碼為 56565-56501，電子郵件身分則可使用 [e-mail]。 注意：這個值可以是個人識別資訊，但一律不得含有 SPII。 這個值會顯示在購買流程等使用者介面中，方便使用者分辨付款方式。 注意：此值或 accountNickname 必須存在，不能兩者都存在。

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 OPTIONAL：這個國家/地區的頂層行政區，例如：美國各州、義大利區域、中國省、日本都/道/府/縣。
postalCodeNumber	string 選用：儘管名稱不同，postalCodeNumber 值通常都是英數字元。例如：「94043」、「SW1W」、「SW1W 9TQ」。
countryCode	string 選用：客戶地址的國家/地區代碼，應為 ISO-3166-1 Alpha-2。
phone	string OPTIONAL：客戶的電話號碼。
emailAddress	string 選填：客戶的電子郵件地址。

AssociateAccountResultCode

關聯帳戶的結果代碼。

列舉
UNKNOWN_RESULT	請不要設定這個預設值！
SUCCESS	連結成功。
USER_AUTHENTICATION_FAILED	即使傳回帳戶驗證套件，使用者驗證卻失敗。
NOT_ELIGIBLE	使用者帳戶不符合這項服務的使用資格。
OTP_NOT_MATCHED	動態密碼與整合商傳送的內容不符。
OTP_ALREADY_USED	動態密碼已使用過。
OTP_LIMIT_REACHED	使用者要求或嘗試驗證的動態密碼過多。
OTP_EXPIRED	動態密碼已失效。