Method: capture

• HTTP 要求
• 要求主體
  • JSON 表示法
• 回應主體
  • JSON 表示法
• MandateDetails
  • JSON 表示法
• MandateWithNotificationDetails
  • JSON 表示法
• CaptureContext
  • JSON 表示法
• CaptureResultCode

在客戶與 Google 持有的帳戶與付款處理方之間進行金錢流動。標頭與 paymentIntegratorAccountId 中的 requestId 組合是冪等鍵，專門用來識別這筆交易。這筆交易的所有變動 (退款) 都會填入 captureRequestId 欄位的 requestId 值。

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

以下是要求範例：

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": "1502220196077"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "googlePaymentToken": "ZXhhbXBsZSB1bmlxdWUgcGF5bWVudCB0b2tlbiB2YWx1ZQ",
  "transactionDescription": "Google - Music",
  "currencyCode": "INR",
  "amount": "728000000",
  "captureContext": {}
}

回應範例如下所示：

{
  "responseHeader": {
    "responseTimestamp": "1481900013178"
  },
  "result": "SUCCESS",
  "paymentIntegratorTransactionId": "aW50ZWdyYXRvciB0cmFuc2FjdGlvbiBpZA"
}

HTTP 要求

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

要求主體

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

JSON 表示法

{ "requestHeader": { object (RequestHeader) }, "paymentIntegratorAccountId": string, "transactionDescription": string, "currencyCode": string, "amount": string, "captureContext": { object (CaptureContext) }, // Union field fopDetails can be only one of the following: "googlePaymentToken": string, "mandateDetails": { object (MandateDetails) }, "mandateWithNotificationDetails": { object (MandateWithNotificationDetails) } // End of list of possible types for union field fopDetails. // 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) 必要項目：所有要求的通用標頭。
paymentIntegratorAccountId	string 必要項目：這是付款整合商帳戶 ID，用於識別這筆交易的相關合約限制。
transactionDescription	string 必要項目：可加入客戶對帳單中的交易說明。已本地化為 requestHeader 中找到的 userLocale。這個格式在未通知的情況下變更，也一律不得剖析。
currencyCode	string 必要項目：以 3 個字母表示的 ISO 4217 貨幣代碼
amount	string (Int64Value format) 必要項目：購買金額，以貨幣單位微量為單位。
captureContext	object (CaptureContext) 必要項目：這次拍攝作業的背景資訊。
聯集欄位 fopDetails。必要項目：這筆交易的 FOP 詳細資料。fopDetails 只能採用下列其中一種設定：
googlePaymentToken	string 兩家公司用來識別彼此交易帳戶的權杖。
mandateDetails	object (MandateDetails) 委託書專屬的付款詳情。
mandateWithNotificationDetails	object (MandateWithNotificationDetails) 授權項目專屬的付款資料 (需要 upcomingTransactionNotification)。
聯集欄位 account_verification。 account_verification 只能採用下列其中一種設定：
authenticationRequestId	string 選用：相關驗證要求的 requestId。如未顯示，代表這項拍攝作業沒有任何驗證連結。 如有這種情況，表示使用者已在這次呼叫前立即完成驗證，或在設定自動付款時間表時完成驗證。
otpVerification	object (OtpVerification) 選用：驗證從 sendOtp 產生的動態密碼所需的資料。只有當使用者經過 sendOtp 路徑時才會顯示。

回應主體

擷取方法的回應物件。

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

JSON 表示法
{ "responseHeader": { object (ResponseHeader) }, "paymentIntegratorTransactionId": string, "userMessage": string, "result": enum (CaptureResultCode), "rawResult": { object (RawResult) }, "transactionLimit": string, "currentBalance": string }

欄位
responseHeader	object (ResponseHeader) 必要項目：所有回應的通用標頭。
paymentIntegratorTransactionId	string 選用：這個 ID 專屬於整合商，由整合商產生。這是整合商可辨識這筆交易的 ID。 為了方便起見，匯款詳細資料中包含這個 ID
userMessage (deprecated)	string 目前從未實作過，將在日後的版本中移除。系統會忽略這個欄位。 已淘汰：如果結果不是 SUCCESS，要向使用者顯示的結果說明。
result	enum (CaptureResultCode) 必要項目：這次擷取的結果。
rawResult	object (RawResult) OPTIONAL：這次擷取的原始結果。有助於通知 Google 的風險引擎和分析系統。在拒絕代碼 – 對應的情況下，資料有時會遺失。整合商可以選擇向 Google 提供原始代碼。舉例來說，信用卡閘道 (整合商) 可利用這個欄位，將 VISA 網路收到的確切拒絕代碼傳送給 Google。在這種情況下，scope 會是「visa」，rawCode 則是 VISA 網路傳回的內容。 如果 result 不是 SUCCESS，此為必填值。
transactionLimit	string (Int64Value format) OPTIONAL：如果結果為 CHARGE_EXCEEDS_TRANSACTION_LIMIT，則這個值是指使用者單筆交易中可支出的最高金額 (以微量為單位)。可用於結構化、向使用者顯示的訊息和拒絕率分析。 這必須是與要求中的 currencyCode 相對的限制。
currentBalance	string (Int64Value format) OPTIONAL：如果結果是 INSUFFICIENT_FUNDS，則這是使用者帳戶中目前的可用餘額 (以微量為單位)。這個 API 是用來向使用者顯示結構化的結構化訊息。 這個值必須與要求中的 currencyCode 相同。

MandateDetails

要取得的委託書詳細資料。

JSON 表示法
{ "mandateId": string }

欄位
mandateId	string 必要項目：Google 在 createMandate 呼叫期間傳送的委託書 ID。

MandateWithNotificationDetails

要擷取的委託書詳細資料，以及必要的通知詳細資料。

JSON 表示法
{ "mandateId": string, "upcomingTransactionNotificationId": string }

欄位
mandateId	string 必要項目：Google 在 createMandate 呼叫期間傳送的委託書 ID。
upcomingTransactionNotificationId	string 必要項目：upcomingTransactionNotification 呼叫的 requestId，目的是預先通知這筆交易。

CaptureContext

這個物件提供有關擷取要求方式的背景資訊。

JSON 表示法
{ "userIpAddress": string }

欄位
userIpAddress	string 選用：這是指使用者於工作階段中進行購買時，使用者裝置的 IP 位址。如果使用者不登入工作階段，這個選項就會空白。如果特定合約未規定有這個欄位，這個欄位就會一律留空。

CaptureResultCode

擷取結果代碼。

列舉
UNKNOWN_RESULT	請不要設定這個預設值！
SUCCESS	成功拍攝並提交商品。
CHARGE_EXCEEDS_TRANSACTION_LIMIT	這項擷取要求的 amount 超過單筆交易上限。如果這個代碼是用於傳送使用者訊息時填入 transactionLimit 欄位，
CHARGE_EXCEEDS_DAILY_LIMIT	這個帳戶已超過每日上限，因此無法用於購物。
CHARGE_EXCEEDS_MONTHLY_LIMIT	這個帳戶已超過每月上限，因此無法立即用於購物。
CHARGE_UNDER_LIMIT	這項擷取要求的 amount 未達最低交易金額。
INSUFFICIENT_FUNDS	此帳戶的資金不足，無法保證進行這項擷取。
ACCOUNT_DOES_NOT_SUPPORT_CURRENCY	這個帳戶不支援要求的貨幣。
ACCOUNT_CLOSED	整合商所保存的使用者帳戶已關閉。 如果傳回這個值，Google 會關閉使用者的付款方式。使用者必須再次完成連結流程，才能新增付款方式。
ACCOUNT_CLOSED_ACCOUNT_TAKEN_OVER	整合商的使用者帳戶已關閉，疑似帳戶接管。 如果傳回這個值，Google 會關閉使用者的付款方式。使用者必須再次完成連結流程，才能新增付款方式。
ACCOUNT_ON_HOLD	帳戶處於暫停使用狀態。
ACCOUNT_CLOSED_FRAUD	整合商所持有的使用者帳戶因詐欺行為已遭關閉。 如果傳回這個值，Google 會關閉使用者的付款方式。使用者必須再次完成連結流程，才能新增付款方式。
GOOGLE_PAYMENT_TOKEN_INVALIDATED_BY_USER	該帳戶仍然有效，但整合商的使用者對 GPT 已經失效。 如果傳回這個值，Google 會關閉使用者的付款方式。使用者必須再次完成連結流程，才能新增付款方式。
TOKEN_REFRESH_REQUIRED	傳回此項目需要使用者執行重新整理流程。
OTP_NOT_MATCHED	動態密碼與整合商傳送的內容不符。
OTP_ALREADY_USED	動態密碼已使用過。
RISK_DECLINED	整合商端的風險檢查，因此交易遭到拒絕。 這筆款項是永久性的失敗，Google 不會因此關閉使用者的付款方式。
NO_GOOD_FUNDING_SOURCE_AVAILABLE	使用者未在帳戶中設定任何可用於支付交易費用的資金來源。
FUNDING_SOURCE_UNAVAILABLE	發卡機構或資金來源無法使用，如果重試了這筆現有付款，就無法成功。 如果合作夥伴傳回 4xx 或 5xx 回應代碼，Google 就會重試付款。因此，如果主要資金來源恢復可用，合作夥伴又重新支付同一筆款項，就可能成功傳回一組回應代碼。不過，如果發生技術問題，導致 Google 重試付款失敗，合作夥伴可以傳回「FUNDING_SOURCE_UNAVAILABLE」，藉此告知 Google 不應重試同筆付款。 注意：Google 可能還是會重試這筆付款，但只能嘗試使用不同的 requestId，但系統會將這項付款要求標示為「已拒絕」。
MANDATE_NOT_ACTIVE	這項拍攝作業使用的委託書已失效。這個傳回值會導致 Google 關閉使用者的委託書付款方式。
UPCOMING_TRANSACTION_NOTIFICATION_EXPIRED	傳送給使用者的週期性委託付款通知已失效。