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。必要項目：這項 Capture 交易的付款方式詳細資料。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) 選用：如果結果是 CHARGE_EXCEEDS_TRANSACTION_LIMIT，則這是指使用者在一筆交易中可支出的最高金額 (以微量為單位)。這可用於以結構化的方式向使用者顯示訊息和拒絕率分析。 這必須是與要求 currencyCode 相關的限制。
currentBalance	string (Int64Value format) 選用：如果結果是 INSUFFICIENT_FUNDS，則這是使用者帳戶目前可用的餘額 (以微量為單位)。這可用於向向使用者顯示的結構化訊息。 這個值必須與要求中的 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 超過單筆交易上限。如果此代碼用於填入交易限制欄位，以便進行使用者訊息，
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	系統傳送給使用者的週期性委託書付款通知已過期。