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 验证的用户地址。

响应正文

如果成功，响应正文将包含结构如下的数据：

付款集成商托管的 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

必需：此请求的唯一标识符。

这是一个字符串，长度上限为 100 个字符，且仅包含字符“a-z”、“A-Z”、“0-9”、“:”、“-”和“_”。
requestTimestamp

string (int64 format)

必需：此请求的时间戳，以从公元纪年开始计算的毫秒数表示。接收方应验证此时间戳是否为“现在”的 ±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)

必需：此请求的版本。

版本

Version 对象，它是传统版 a.b.c 版本结构的结构化形式。同一版本号的主要版本保证是兼容的。请注意，次要和修订可能会频繁更改，恕不另行通知。集成商必须支持针对同一主要版本的所有请求。

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

number

必需：主要版本。针对与不同版本的兼容性请求进行标记，不保证兼容。

minor

number

必需：次要版本。这表示存在重大问题修复。

revision

number

必需：次要版本。这表示修复了一些小 bug。

StandardCard

卡片的标准表示法

JSON 表示法 
{
  "accountNumber": string,
  "expiryDate": string,
  "cvn": string
}
字段
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

可选：此术语不太准确，但通常是指地址的城市/城镇部分。对于没有明确定义 locality 或者其无法很好地对应这个结构的区域，应将 localityName 留空并使用 address_line。

示例：美国的城市、意大利的市镇、英国的邮镇。
administrativeAreaName

string

可选：此国家/地区中用户的账单邮寄地址的顶级行政区划。

示例：美国州、意大利地区、英国构成国、日本都道府县

如果国家/地区 == US，则此值应为 2 个字符的美国州缩写。
postalCodeNumber

string

可选：用户的账单邮寄地址邮政编码。

countryCode

string

可选：用户账单邮寄地址的国家/地区代码，采用 ISO-3166-1 Alpha-2 格式。

ResponseHeader

在从服务器发送的所有响应中定义的标头对象。

JSON 表示法 
{
  "responseTimestamp": string
}
字段
responseTimestamp

string (int64 format)

必需：此响应的时间戳，以自纪元以来的毫秒数表示。接收方应验证此时间戳是否为“现在”的 ±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 网络
DINACARD DINACARD 网络
DINERS_CLUB DINERS_CLUB 广告联盟
DISCOVER Google 探索网络
EFTPOS EFTPOS 网络
ELO ELO 网络
ENROUTE ENROUTE 网络
FELICA FELICA 网络
GE_CAPITAL GE_CAPITAL 网络
HIPERCARD HIPERCARD 网络
ID ID 广告网络
INTERAC INTERAC 网络
JCB JCB 网络
LASER 激光网络
MAESTRO MAESTRO 网络
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 发送了 CVN，它已经过验证且匹配。对应的代码为广告联盟结果代码“M”。
MISMATCH Google 发送了 CVN 码，它已经过验证，但不匹配。对应的广告联盟结果代码为“N”。