更新到最新版本
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
Google Pay API 于 2018 年 7 月为 PaymentDataRequest
和 IsReadyToPayRequest
对象推出了新的对象结构。本指南介绍了如何将针对 Google Pay API 版本 1 设置了格式的对象更新为针对版本 2 设置了格式的对象。
付款方式
Google Pay API 版本 2 中的每个请求对象均指定了 API 版本。
Google Pay API 版本 1 支持将卡作为唯一的付款方式。在 Google Pay API 版本 2 中,CARD
付款方式是多个可能的付款方式选项之一。以前将 allowedPaymentMethods
值指定为 CARD
的网站现在必须将 allowedAuthMethods
值设置为 PAN_ONLY
。以前将 allowedPaymentMethods
值指定为 TOKENIZED_CARD
的网站现在必须将 allowedAuthMethods
值设置为 CRYPTOGRAM_3DS
。
允许的支付卡网络会与这些网络中的支付卡对应的受支持的身份验证方法一起指定。
apiVersion 1
{
allowedPaymentMethods: [
'CARD',
'TOKENIZED_CARD'
],
cardRequirements: {
allowedCardNetworks: [
'AMEX',
'DISCOVER',
'JCB',
'MASTERCARD',
'VISA'
]
}
}
apiVersion 2
{
apiVersion: 2,
apiVersionMinor: 0,
allowedPaymentMethods: [{
type: 'CARD',
parameters: {
allowedAuthMethods: [
'PAN_ONLY',
'CRYPTOGRAM_3DS'
],
allowedCardNetworks: [
'AMEX',
'DISCOVER',
'JCB',
'MASTERCARD',
'VISA'
]
}
}]
}
允许的支付卡网络及其身份验证方法包含在 CARD
付款方式的 IsReadyToPayRequest
中。
卡支付数据令牌化
Google Pay API 会返回加密的卡数据,该数据将由您的指定网关引用或在您的服务器上进行解密。Google Pay API 版本 2 将付款方式令牌化移到了 CARD
付款方式内。
apiVersion 1
{
paymentMethodTokenizationParameters: {
tokenizationType: 'PAYMENT_GATEWAY',
parameters: {
'gateway': 'example',
'gatewayMerchantId': 'exampleMerchantId'
}
}
}
apiVersion 2
{
allowedPaymentMethods: [{
type: 'CARD',
tokenizationSpecification: {
type: 'PAYMENT_GATEWAY',
parameters: {
'gateway': 'example',
'gatewayMerchantId': 'exampleMerchantId'
}
}
}]
}
Google 商家 ID
Google 商家 ID 是 Google Pay API 版本 1 中的顶级属性。现在,Google 商家 ID 放置在具有可选商家名称的 MerchantInfo
对象中。
apiVersion 1
{
merchantId: '12345678901234567890'
}
apiVersion 2
{
merchantInfo: {
merchantId: '12345678901234567890'
}
}
帐单邮寄地址
可选的帐单邮寄地址和帐单电话号码与 CARD
付款方式相关联。如果某个网站请求了帐单邮寄地址,那么与预期响应相关的任何配置都会放置在 BillingAddressParameters
对象内。
apiVersion 1
{
cardRequirements: {
billingAddressRequired: true,
billingAddressFormat: 'FULL'
},
phoneNumberRequired: true
}
apiVersion 2
{
allowedPaymentMethods: [{
type: 'CARD',
parameters: {
billingAddressRequired: true,
billingAddressParameters: {
format: 'FULL',
phoneNumberRequired: true
}
}
}]
}
送货地址
可选的送货地址要求仍位于 PaymentDataRequest
对象的顶层。shippingAddressRequirements
属性已重命名为 shippingAddressParameters
。
在请求电话号码时,早期的 Google Pay API 响应可能会将电话号码作为送货地址的一部分返回。现在任何版本的 Google Pay API 都不再支持送货电话号码。任何请求送货联系电话号码的响应处理程序都必须进行更新。
apiVersion 1
{
shippingAddressRequired: true,
shippingAddressRequirements: {
allowedCountryCodes: [
'US',
'CA'
]
}
}
apiVersion 2
{
shippingAddressRequired: true,
shippingAddressParameters: {
allowedCountryCodes: [
'US',
'CA'
]
}
}
PaymentData 响应
PaymentDataRequest
中将 apiVersion
属性值设置为 2
的网站的 PaymentData
对象响应已更改为将卡作为多个可能的付款数据响应之一来引用。PaymentDataRequest
对象中包含的 apiVersion
和 apiVersionMinor
属性会显示在 PaymentData
响应中,以指明预期格式。
apiVersion 1
{
// no version specified
}
apiVersion 2
{
apiVersion: 2,
apiVersionMinor: 0
}
所选付款方式及其令牌化的相关信息位于 paymentMethodData
属性中。卡付款方式的 cardInfo
对象中移除了两个属性:cardClass
和 cardImageUri
。
apiVersion 1
{
cardInfo: {
cardDescription: 'Visa •••• 1234',
cardNetwork: 'VISA',
cardDetails: 1234
},
paymentMethodToken: {
tokenizationType: 'PAYMENT_GATEWAY',
token: 'examplePaymentMethodToken'
}
}
apiVersion 2
{
paymentMethodData: {
type: 'CARD',
description: 'Visa •••• 1234',
info: {
cardNetwork: 'VISA',
cardDetails: '1234'
},
tokenizationData: {
type: 'PAYMENT_GATEWAY',
token: 'examplePaymentMethodToken'
}
}
}
加密的消息响应
指定 DIRECT
付款方式令牌化类型并接受 API 版本 1 TOKENIZED_CARD
付款方式的网站必须更新其对解密的 encryptedMessage
属性的处理方式。网站必须执行此操作,才能继续将使用 3D 安全密文和可选的电子商务指示器 (ECI) 进行身份验证的 Android 设备令牌转发到您的网关或处理方。卡是 CARD
的一种 paymentMethod
,其中包含有关 paymentMethodDetails.authMethod
中所选卡的身份验证方法的额外信息。
apiVersion 1
{
"paymentMethod": "TOKENIZED_CARD",
"paymentMethodDetails": {
"authMethod": "3DS",
"dpan": "1111222233334444",
"expirationMonth": 10,
"expirationYear": 2020,
"3dsCryptogram": "AAAAAA...",
"3dsEciIndicator": "eci indicator"
}
}
apiVersion 2
{
"paymentMethod": "CARD",
"paymentMethodDetails": {
"authMethod": "CRYPTOGRAM_3DS",
"pan": "1111222233334444",
"expirationMonth": 10,
"expirationYear": 2020,
"cryptogram": "AAAAAA...",
"eciIndicator": "eci indicator"
}
}
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2024-10-16。
[null,null,["最后更新时间 (UTC):2024-10-16。"],[[["\u003cp\u003eGoogle Pay API \u003ccode\u003ePaymentDataRequest\u003c/code\u003e and \u003ccode\u003eIsReadyToPayRequest\u003c/code\u003e objects have been updated with new structures in version 2, requiring updates to existing integrations.\u003c/p\u003e\n"],["\u003cp\u003eVersion 2 introduces explicit API versioning and expands payment methods beyond just cards, requiring adjustments to \u003ccode\u003eallowedPaymentMethods\u003c/code\u003e and \u003ccode\u003eallowedAuthMethods\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003ePayment method tokenization, Google merchant ID, billing address configuration, and shipping address parameters have been relocated within the new object structure.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003ePaymentData\u003c/code\u003e response format has been revised to include API version information and nest card details within \u003ccode\u003epaymentMethodData\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eHandling of encrypted message responses for tokenized cards requires updates to accommodate the new \u003ccode\u003epaymentMethod\u003c/code\u003e and \u003ccode\u003epaymentMethodDetails\u003c/code\u003e structure.\u003c/p\u003e\n"]]],["The Google Pay API updated its object structures to version 2. Key changes include specifying the API version in each request and expanding payment methods beyond just `CARD`. Version 2 requires setting `allowedAuthMethods` to `PAN_ONLY` or `CRYPTOGRAM_3DS` instead of `allowedPaymentMethods`. Tokenization moved inside the `CARD` payment method, and the merchant ID is now within the `MerchantInfo` object. Billing and shipping address requirements are reorganized. Finally, `PaymentData` responses now specify the API version.\n"],null,["# Update to latest version\n\nThe Google Pay API introduced new object structures for\n[`PaymentDataRequest`](/pay/api/web/reference/request-objects#PaymentDataRequest) and\n[`IsReadyToPayRequest`](/pay/api/web/reference/request-objects#IsReadyToPayRequest) objects in July 2018. This guide explains how to update\nobjects formatted for Google Pay API version 1 to objects formatted for version 2.\n\nPayment methods\n---------------\n\nAn API version is specified with each request object in version 2 of the Google Pay API.\n\nVersion 1 of the Google Pay API supported cards as the only form of payment. The\n`CARD` [payment method](/pay/api/web/reference/request-objects#PaymentMethod)\nis one of multiple possible payment method options in version 2 of the Google Pay API. Sites that\npreviously specified an `allowedPaymentMethods` value of `CARD` must now set\nan `allowedAuthMethods` value of `PAN_ONLY`. Sites that previously specified\nan `allowedPaymentMethods` value of `TOKENIZED_CARD` must now set an\n`allowedAuthMethods` value of `CRYPTOGRAM_3DS`.\n\nAllowed card networks are specified alongside supported authentication methods for cards on\nthose networks. \n\n### apiVersion 1\n\n```javascript\n{\n allowedPaymentMethods: [\n 'CARD',\n 'TOKENIZED_CARD'\n ],\n cardRequirements: {\n allowedCardNetworks: [\n 'AMEX',\n 'DISCOVER',\n 'JCB',\n 'MASTERCARD',\n 'VISA'\n ]\n }\n}\n```\n\n### apiVersion 2\n\n```javascript\n{\n apiVersion: 2,\n apiVersionMinor: 0,\n allowedPaymentMethods: [{\n type: 'CARD',\n parameters: {\n allowedAuthMethods: [\n 'PAN_ONLY',\n 'CRYPTOGRAM_3DS'\n ],\n allowedCardNetworks: [\n 'AMEX',\n 'DISCOVER',\n 'JCB',\n 'MASTERCARD',\n 'VISA'\n ]\n }\n }]\n}\n```\n\nAllowed card networks and their authentication methods are included in an\n[`IsReadyToPayRequest`](/pay/api/web/reference/request-objects#IsReadyToPayRequest) for a `CARD`\n[payment method](/pay/api/web/reference/request-objects#PaymentMethod \"Object reference: payment method\").\n\nCard payment data tokenization\n------------------------------\n\nThe Google Pay API returns encrypted card data that's referenced by your specified gateway or\ndecrypted on your servers. Version 2 of the Google Pay API moves\n[payment method tokenization](/pay/api/web/reference/request-objects#PaymentMethodTokenizationSpecification \"Object reference: PaymentMethodTokenizationSpecification\")\ninside the `CARD` payment method. \n\n### apiVersion 1\n\n```javascript\n{\n paymentMethodTokenizationParameters: {\n tokenizationType: 'PAYMENT_GATEWAY',\n parameters: {\n 'gateway': '\u003cvar translate=\"no\"\u003eexample\u003c/var\u003e',\n 'gatewayMerchantId': '\u003cvar translate=\"no\"\u003eexampleMerchantId\u003c/var\u003e'\n }\n }\n}\n```\n\n### apiVersion 2\n\n```javascript\n{\n allowedPaymentMethods: [{\n type: 'CARD',\n tokenizationSpecification: {\n type: 'PAYMENT_GATEWAY',\n parameters: {\n 'gateway': '\u003cvar translate=\"no\"\u003eexample\u003c/var\u003e',\n 'gatewayMerchantId': '\u003cvar translate=\"no\"\u003eexampleMerchantId\u003c/var\u003e'\n }\n }\n }]\n}\n```\n\nGoogle merchant ID\n------------------\n\nA Google merchant ID was a top-level property in version 1 of the Google Pay API. Now, the\nGoogle merchant ID is placed inside a\n[`MerchantInfo`](/pay/api/web/reference/request-objects#MerchantInfo) object\nwith an optional merchant name. \n\n### apiVersion 1\n\n```javascript\n{\n merchantId: '12345678901234567890'\n}\n```\n\n### apiVersion 2\n\n```javascript\n{\n merchantInfo: {\n merchantId: '12345678901234567890'\n }\n}\n```\n\nBilling address\n---------------\n\nAn optional billing address and a billing phone number are associated with a `CARD` payment method.\nIf a site requests a billing address, any configuration related to the expected response is placed inside a\n[`BillingAddressParameters`](/pay/api/web/reference/request-objects#BillingAddressParameters) object. \n\n### apiVersion 1\n\n```javascript\n{\n cardRequirements: {\n billingAddressRequired: true,\n billingAddressFormat: 'FULL'\n },\n phoneNumberRequired: true\n}\n```\n\n### apiVersion 2\n\n```javascript\n{\n allowedPaymentMethods: [{\n type: 'CARD',\n parameters: {\n billingAddressRequired: true,\n billingAddressParameters: {\n format: 'FULL',\n phoneNumberRequired: true\n }\n }\n }]\n}\n```\n\nShipping address\n----------------\n\nAn optional shipping address requirement remains at the top level of the\n[`PaymentDataRequest`](/pay/api/web/reference/request-objects#PaymentDataRequest) object.\nThe `shippingAddressRequirements` property has been renamed\n[`shippingAddressParameters`](/pay/api/web/reference/request-objects#ShippingAddressParameters).\n\nEarlier Google Pay API responses might have returned a phone number as part of the shipping address\nwhen a phone number was requested. A shipping phone number is no longer supported by the Google Pay API in any version.\nAny response handlers that expect a shipping phone number must be updated. \n\n### apiVersion 1\n\n```javascript\n{\n shippingAddressRequired: true,\n shippingAddressRequirements: {\n allowedCountryCodes: [\n 'US',\n 'CA'\n ]\n }\n}\n```\n\n### apiVersion 2\n\n```javascript\n{\n shippingAddressRequired: true,\n shippingAddressParameters: {\n allowedCountryCodes: [\n 'US',\n 'CA'\n ]\n }\n}\n```\n\nPaymentData response\n--------------------\n\nThe [`PaymentData`](/pay/api/web/reference/response-objects#PaymentData) object response\nfor sites that set an `apiVersion` property value of `2` in\n[`PaymentDataRequest`](/pay/api/web/reference/request-objects#PaymentDataRequest)\nhas changed to reference cards as one of multiple possible payment data responses.\nThe `apiVersion` and `apiVersionMinor` properties included in the\n[`PaymentDataRequest`](/pay/api/web/reference/request-objects#PaymentDataRequest) object\nappear in the\n[`PaymentData`](/pay/api/web/reference/response-objects#PaymentData) response to indicate\nthe expected format. \n\n### apiVersion 1\n\n```javascript\n{\n // no version specified\n}\n```\n\n### apiVersion 2\n\n```javascript\n{\n apiVersion: 2,\n apiVersionMinor: 0\n}\n```\n\nInformation about a selected payment method and its tokenization is placed inside the\n[`paymentMethodData`](/pay/api/web/reference/response-objects#PaymentMethodData) property.\nTwo properties have been removed from the card payment method's `cardInfo` object:\n`cardClass` and `cardImageUri`. \n\n### apiVersion 1\n\n```javascript\n{\n cardInfo: {\n cardDescription: 'Visa •••• 1234',\n cardNetwork: 'VISA',\n cardDetails: 1234\n },\n paymentMethodToken: {\n tokenizationType: 'PAYMENT_GATEWAY',\n token: 'examplePaymentMethodToken'\n }\n}\n```\n\n### apiVersion 2\n\n```javascript\n{\n paymentMethodData: {\n type: 'CARD',\n description: 'Visa •••• 1234',\n info: {\n cardNetwork: 'VISA',\n cardDetails: '1234'\n },\n tokenizationData: {\n type: 'PAYMENT_GATEWAY',\n token: 'examplePaymentMethodToken'\n }\n }\n}\n```\n\nEncrypted message response\n--------------------------\n\nSites that specify a `DIRECT` payment method tokenization type and accept an\nAPI version 1 payment method of `TOKENIZED_CARD` must update how they handle the\ndecrypted `encryptedMessage` property. The site must do this to continue to forward\nAndroid device tokens authenticated with a 3-D Secure cryptogram and optional electronic commerce\nindicator (ECI) to your gateway or processor. Cards are a `paymentMethod` of\n`CARD`, with additional information about the selected card's authentication method in\n`paymentMethodDetails.authMethod`. \n\n### apiVersion 1\n\n```javascript\n{\n \"paymentMethod\": \"TOKENIZED_CARD\",\n \"paymentMethodDetails\": {\n \"authMethod\": \"3DS\",\n \"dpan\": \"1111222233334444\",\n \"expirationMonth\": 10,\n \"expirationYear\": 2020,\n \"3dsCryptogram\": \"AAAAAA...\",\n \"3dsEciIndicator\": \"eci indicator\"\n }\n}\n```\n\n### apiVersion 2\n\n```javascript\n{\n \"paymentMethod\": \"CARD\",\n \"paymentMethodDetails\": {\n \"authMethod\": \"CRYPTOGRAM_3DS\",\n \"pan\": \"1111222233334444\",\n \"expirationMonth\": 10,\n \"expirationYear\": 2020,\n \"cryptogram\": \"AAAAAA...\",\n \"eciIndicator\": \"eci indicator\"\n }\n}\n```"]]