本頁面由 Cloud Translation API 翻譯而成。

Method: card.verifycard

驗證使用者的卡片，確認是否有效。

Google 會呼叫這個方法來驗證使用者的卡片詳細資料，並確認卡片是否能用於付款。這個通話不會轉移任何款項，且使用者的帳戶也不應出現永久變更。

要求範例如下：


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "ZWNobyB0cmFuc2FjdGlvbg",
    "requestTimestamp": "1481855969503"
  },
  "standardCard": {
    "accountNumber": "4123456789101112",
    "expiryDate": "01/2020",
    "cvn": "123"
  },
  "avsData": {
    "streetAddress": "123 Main St APT #200",
    "localityName": "Springfield",
    "administrativeAreaName": "CO",
    "countryCode": "US"
  }
}

回應範例如下所示：


{
  "responseHeader": {
    "responseTimestamp": "1481855970403",
  },
  "cardNetworkResult": {
    "network": "VISA",
    "iso8583Result": "00",
    "rawNetworkResult": "00"
  },
  "avsResult": {
    "rawAvsResult": "B",
    "streetAddress": "MATCH",
    "localityName": "MATCH",
    "administrativeAreaName": "MATCH",
    "postalCodeNumber": "NOT_SENT",
    "countryCode": "SKIPPED"
  },
  "cvnResult": "MATCH"
}

HTTP 要求

POST https://card-verification-service.google.com/v1/card/verifycard

這個網址使用 gRPC 轉碼語法。

要求主體

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

JSON 表示法
{ "requestHeader": { object(`RequestHeader`) }, "standardCard": { object(`StandardCard`) }, "avsData": { object(`AvsData`) } }

欄位

欄位
`requestHeader`	`object(RequestHeader)` 必要項目：所有要求的通用標頭。
`standardCard`	`object(StandardCard)` 必要項目：使用者付款卡的相關資料。
`avsData`	`object(AvsData)` 選用：要經過 AVS 驗證的使用者地址。

requestHeader

object(RequestHeader)

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

standardCard

object(StandardCard)

必要項目：使用者付款卡的相關資料。

avsData

object(AvsData)

選用：要經過 AVS 驗證的使用者地址。

回應主體

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

付款整合商代管 card.verifycard 方法的回應物件。

JSON 表示法
{ "responseHeader": { object(`ResponseHeader`) }, "cardNetworkResult": { object(`CardNetworkResult`) }, "avsResult": { object(`AvsResult`) }, "cvnResult": enum(`CvnResult`) }

欄位
`responseHeader`	`object(ResponseHeader)` 必要項目：所有回應的通用標頭。
`cardNetworkResult`	`object(CardNetworkResult)` 必要項目：向發卡機構核發授權的結果。
`avsResult`	`object(AvsResult)` OPTIONAL：驗證要求中傳送的地址欄位的結果。如果要求中已設定 `addressVerificationSystemData`，則此為必要欄位。
`cvnResult`	`enum(CvnResult)` 必要項目：驗證要求中傳送的 CVN 驗證結果。如果要求中未設定 CVN，這個值應為 `NOT_SENT`。

RequestHeader

可對傳送至伺服器的所有要求定義的標頭物件。

JSON 表示法
{ "requestId": string, "requestTimestamp": string, "userLocale": string, "protocolVersion": { object(`Version`) } }

欄位
`requestId`	`string` 必要項目：要求的專屬 ID。這個字串的長度上限為 100 個半形字元，且只能包含「a-z」、「A-Z」、「0-9」、「:」、「-」和「_」等字元。
`requestTimestamp`	`string (int64 format)` REQUIRED：這項要求的時間戳記，以 Epoch 紀元時間起算的毫秒數表示。接收端應驗證這個時間戳記是否為「現在」的 ±60 秒。重試時此要求的時間戳記不是冪等。
`userLocale (deprecated)`	`string` 從未實作過這項功能，我們會在日後的版本中將其移除。系統會忽略這個欄位。選用：由二或三個字母組成的 ISO 639-2 Alpha 3 語言代碼 (選填)，後面加上連字號和 ISO 3166-1 Alpha-2 國家/地區代碼，例如「pt」、「pt-BR」、「fil」或「fil-PH」。這有助於在回應中呈現 `user_message` 欄位。
`protocolVersion`	`object(Version)` 必要項目：要求的版本。

版本

傳統版 a.b.c 版本結構的結構化格式版本物件。只要是相同數字的主要版本，我們保證會相容。請注意，微幅和修訂可能經常變更，恕不另行通知。整合商必須支援對相同主要版本的所有要求。

JSON 表示法
{ "major": number, "minor": number, "revision": number }

欄位

欄位
`major`	`number` 必要項目：主要版本。標示此選項，代表不同版本的相容性要求不保證能相容。
`minor`	`number` 必要項目：子版本。這代表了重大錯誤修正。
`revision`	`number` 必要項目：子版本。這代表微小的錯誤修正。

major

number

必要項目：主要版本。標示此選項，代表不同版本的相容性要求不保證能相容。

minor

number

必要項目：子版本。這代表了重大錯誤修正。

revision

number

必要項目：子版本。這代表微小的錯誤修正。

StandardCard

卡片的標準表示法

JSON 表示法
{ "accountNumber": string, "expiryDate": string, "cvn": string }

欄位

欄位
`accountNumber`	`string` 必要項目：純文字格式的卡片主要帳號 (PAN)。
`expiryDate`	`string` 選用：卡片到期日，格式為 MM/YYYY。選用原因：某些地區的部分信用卡沒有到期日。
`cvn`	`string` 選用：如果 Google 向使用者收集的 CVN 列在此處，則該 CVN 應通過驗證。

accountNumber

string

必要項目：純文字格式的卡片主要帳號 (PAN)。

expiryDate

string

選用：卡片到期日，格式為 MM/YYYY。選用原因：某些地區的部分信用卡沒有到期日。

cvn

string

選用：如果 Google 向使用者收集的 CVN 列在此處，則該 CVN 應通過驗證。

AvsData

包含需要 AVS 驗證的地址欄位。

JSON 表示法
{ "streetAddress": string, "localityName": string, "administrativeAreaName": string, "postalCodeNumber": string, "countryCode": string }

欄位
`streetAddress`	`string` 選用：使用者帳單地址的街道地址。當使用者提供多行輸入街道地址時 (例如一行是公寓號碼)，這些行會以空格串連起來。
`localityName`	`string` 選用：這是模糊的字詞，但通常是指地址的縣市/鄉鎮部分。如為未明確定義縣市或國家/地區不適用該結構的區域 (例如日本和中國)，請將 localityName 留白，改用 address_line。範例：美國城市、義大利市鎮、英國郵鎮。
`administrativeAreaName`	`string` 選用：此國家/地區為使用者帳單地址的頂層行政劃分。範例：美國各州、義大利地區、英國組成國家、日本的都/道/府/縣如果國家/地區 == US，這個值應為美國州別的 2 個字元縮寫。
`postalCodeNumber`	`string` 選用：使用者的帳單郵遞區號。
`countryCode`	`string` 選用：使用者帳單地址的國家/地區代碼，採 ISO-3166-1 Alpha-2 格式。

ResponseHeader

這個標頭物件定義於伺服器傳送的所有回應上。

JSON 表示法
{ "responseTimestamp": string }

欄位

欄位
`responseTimestamp`	`string (int64 format)` REQUIRED：此回應的時間戳記，以 Epoch 紀元時間起算的毫秒數表示。接收端應驗證這個時間戳記是否為「現在」的 ±60 秒。

responseTimestamp

string (int64 format)

REQUIRED：此回應的時間戳記，以 Epoch 紀元時間起算的毫秒數表示。接收端應驗證這個時間戳記是否為「現在」的 ±60 秒。

CardNetworkResult

包含網路以及該網路的原始結果代碼。

JSON 表示法
{ "network": enum(`Network`), "iso8583Result": string, "rawNetworkResult": string }

欄位

欄位
`network`	`enum(Network)` 必要項目：結果代碼的來源網路。
`iso8583Result`	`string` 必要項目：聯播網傳回的 ISO-8583 傳回代碼。如果網路使用自己的回應代碼格式，整合商必須將這些回應代碼對應至 ISO-8583 傳回代碼。
`rawNetworkResult`	`string` 必要項目：從網路傳回的原始值。如果網路使用 ISO-8583 傳回代碼，這個欄位和 `iso8583Result` 中的值就會相同。這個欄位用於通知 Google 的風險引擎，最適合使用自家回應代碼的網路。

network

enum(Network)

必要項目：結果代碼的來源網路。

iso8583Result

string

必要項目：聯播網傳回的 ISO-8583 傳回代碼。

如果網路使用自己的回應代碼格式，整合商必須將這些回應代碼對應至 ISO-8583 傳回代碼。

rawNetworkResult

string

必要項目：從網路傳回的原始值。如果網路使用 ISO-8583 傳回代碼，這個欄位和 iso8583Result 中的值就會相同。這個欄位用於通知 Google 的風險引擎，最適合使用自家回應代碼的網路。

網路

定義可能傳回 rawResult 的可能發卡組織。

列舉
`UNKNOWN_NETWORK`	無法辨識網路
`NETWORK_NOT_INVOLVED`	如果交易遭拒並非來自網路，例如整合商在交易從發卡機構傳出之前拒絕購買交易，請使用這個值。
`AMEX`	AMEX 網路
`COMPROCARD`	COMPROCARD 網路
`DANKORT`	DANKORT 聯播網
`DINACARD`	DINACARD 網路
`DINERS_CLUB`	DINERS_CLUB 網路
`DISCOVER`	探索網路
`EFTPOS`	EFTPOS 網路
`ELO`	ELO 網路
`ENROUTE`	ENROUTE 網路
`FELICA`	FELICA 網路
`GE_CAPITAL`	GE_CAPITAL 網路
`HIPERCARD`	HIPERCARD 聯播網
`ID`	ID 聯播網
`INTERAC`	INTERAC 網路
`JCB`	JCB 網路
`LASER`	LASER 網路
`MAESTRO`	MAESTRO 網路
`MASTERCARD`	MASTERCARD 聯播網
`PPT`	PPT 網路
`QUICPAY`	QUICPAY 聯播網
`RUPAY`	RUPAY 聯播網
`SBERCARD`	SBERCARD 網路
`SOLO`	SOLO 網路
`SYNCHRONY`	SYNCHRONY 網路
`UNIONPAY`	UNIONPAY 聯播網
`VISA`	VISA 網路

AvsResult

驗證要求中提供的地址欄位的結果。

所有欄位皆為必填，因為我們希望每個欄位都有明確的結果，且不依賴缺少欄位做為默示結果。

JSON 表示法

JSON 表示法
{ "rawAvsResult": string, "streetAddress": enum(`VerificationResult`), "localityName": enum(`VerificationResult`), "administrativeAreaName": enum(`VerificationResult`), "postalCodeNumber": enum(`VerificationResult`), "countryCode": enum(`VerificationResult`) }

{
  "rawAvsResult": string,
  "streetAddress": enum(VerificationResult),
  "localityName": enum(VerificationResult),
  "administrativeAreaName": enum(VerificationResult),
  "postalCodeNumber": enum(VerificationResult),
  "countryCode": enum(VerificationResult)
}

欄位
`rawAvsResult`	`string` 必要項目：發卡機構傳回的原始 AVS 值。
`streetAddress`	`enum(VerificationResult)` 必要項目：驗證在要求的 `addressVerificationSystemData` 欄位中傳送的 `streetAddress` 的結果。如果要求中未設定這個欄位，則該值應為「NOT_SENT」。
`localityName`	`enum(VerificationResult)` 必要項目：驗證在要求的 `addressVerificationSystemData` 欄位中傳送的 `localityName` 的結果。如果要求中未設定這個欄位，則該值應為「NOT_SENT」。
`administrativeAreaName`	`enum(VerificationResult)` 必要項目：驗證在要求的 `addressVerificationSystemData` 欄位中傳送的 `administrativeAreaName` 的結果。如果要求中未設定這個欄位，則該值應為「NOT_SENT」。
`postalCodeNumber`	`enum(VerificationResult)` 必要項目：驗證在要求的 `addressVerificationSystemData` 欄位中傳送的 `postalCodeNumber` 的結果。如果要求中未設定這個欄位，則該值應為「NOT_SENT」。
`countryCode`	`enum(VerificationResult)` 必要項目：驗證在要求的 `addressVerificationSystemData` 欄位中傳送的 `countryCode` 的結果。如果要求中未設定這個欄位，則該值應為「NOT_SENT」。

VerificationResult

列舉
`UNKNOWN_AVS_MATCH`	切勿設定這個預設值！
`NOT_SENT`	Google 並未傳送這個欄位，因此無法處理。
`MATCH`	Google 將欄位傳送給整合商，經 AVS 檢查後與預期值相符。
`MISMATCH`	Google 將欄位傳送給整合商，已透過 AVS 檢查，但與預期值不符。
`SKIPPED`	Google 將這個欄位傳送給整合商，但整合商沒有檢查這個欄位。
`NOT_SPECIFIED`	Google 將欄位傳送給整合商，整合商已透過 AVS 檢查該欄位，但 AVS 結果代碼未提供足夠的資訊，因此整合商無法判斷該欄位是否與預期值相符。

CvnResult

驗證要求中提供的 CVN 結果。

列舉
`UNKNOWN_CVN_RESULT`	切勿設定這個預設值！
`NOT_SENT`	由於 Google 未提供 CVN，因此無法驗證。
`NOT_VERIFIED`	Google 傳送了 CVN，但尚未驗證。這與「F」的網路結果代碼相對應
`MATCH`	Google 寄出的 CVN 已通過驗證，且該資訊已相符。這與網路結果代碼「M」相對應。
`MISMATCH`	Google 傳送的 CVN 已通過驗證，但不符。這與網路結果代碼「N」相對應。

Method: card.verifycard 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

HTTP 要求

要求主體

回應主體

RequestHeader

版本

StandardCard

AvsData

ResponseHeader

CardNetworkResult

網路

AvsResult

VerificationResult

CvnResult

Method: card.verifycard