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)

OPTIONAL：要由 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)

選用：驗證要求中傳送的地址欄位後的結果。

如果要求中已設定 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)

必要項目：這項要求的時間戳記，以 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

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

StandardCard

卡片的標準表示法

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

string

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

expiryDate

string

選用：卡片的到期日，格式為 MM/YYYY。選用，因為某些區域中的特定卡片沒有到期日。

cvn

string

選用：如果 Google 從這裡提供的使用者收集 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

OPTIONAL：使用者的帳單郵遞區號。

countryCode

string

選用：使用者帳單地址的國家/地區代碼，採用 ISO-3166-1 Alpha-2 格式。

ResponseHeader

從伺服器傳送的所有回應中定義的標頭物件。

JSON 表示法 
{
  "responseTimestamp": string
}
欄位
responseTimestamp

string (int64 format)

必要項目：此回應的時間戳記，以 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 的風險引擎，而且對於使用自有回應代碼的網路最為實用。

網路

定義可能傳回 rawResult 的可能發卡機構。

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

AvsResult

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

因為我們希望每個欄位都有明確的結果，而非仰賴欄位隱含結果，因此所有欄位皆為必填。

JSON 表示法 
{
  "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 傳送，且已通過驗證且相符。此值對應於網路結果代碼「M」。
MISMATCH 信用卡驗證碼是由 Google 傳送，但已通過驗證，但不相符。此值對應網路結果代碼「N」。