对象参考

本页中的参考内容介绍了可在您的网站中使用的 Google Pay API 对象选项,涉及的对象共有三种:

请求对象

为了配置预期体验,系统会向 Google Pay API 客户端库中的类方法传递对象。需要配置多个请求对象才能向 Google Pay API 发出请求。

PaymentOptions

当您测试完您的实现并准备好接收来自买家的付款之后,就可以为正式版环境配置此对象。

如果您在集成中设置了动态价格更新,请务必添加 MerchantInfoPaymentDataCallbacks 字段。

属性 类型 必要性 说明
environment 字符串 可选
  • PRODUCTION:用于在为网域指定和配置有效的 Google 商家 ID 时返回可扣款的付款方式。
  • TEST:适用于测试的虚拟付款方式(默认)。
MerchantInfo MerchantInfo 可选 此对象可提供请求付款数据的商家的相关信息。
paymentDataCallbacks PaymentDataCallbacks 可选 此对象可声明用于动态价格更新的回调。

示例

以下示例配置使用了适用于测试环境的不可扣款的付款方式。其中包含商家信息和付款数据回调。

{
  environment: "TEST",
  merchantInfo: {
    merchantName: "Example Merchant",
    merchantId: "0123456789"
  },
  paymentDataCallbacks: {
    onPaymentDataChanged: onPaymentDataChanged,
    onPaymentAuthorized: onPaymentAuthorized
  }
}

IsReadyToPayRequest

此对象指定哪些付款方式受支持。

属性 类型 必要性 说明
apiVersion 数值 必需 主要 API 版本。对于此规范,该值为 2
apiVersionMinor 数值 必需 次要 API 版本。对于此规范,该值为 0
allowedPaymentMethods PaymentMethod[] 必需

指定是否支持 Google Pay API 所支持的一种或多种付款方式。

不需要 tokenizationSpecification 即可确定查看者是否已准备好付款。为每个受支持的 PaymentMethod 提供所有必需的 parameters 属性。

existingPaymentMethodRequired 布尔值 可选

如果设为 true,则 IsReadyToPayResponse 对象会包含一个额外属性,该属性用于说明访问者是否准备好使用 allowedPaymentMethods 中指定的一种或多种付款方式付款。

示例

此示例显示了如何为所有受支持的支付卡网络的支付卡和 Android 设备令牌提供支持。

{
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "allowedPaymentMethods": [
    {
      "type": "CARD",
      "parameters": {
        "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
        "allowedCardNetworks": ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"]
      }
    }
  ]
}

PaymentDataRequest

使用此对象可配置您的网站对 Google Pay API 的支持。

属性 类型 必要性 说明
apiVersion 数值 必需 主要 API 版本。对于此规范,该值为 2
apiVersionMinor 数值 必需 次要 API 版本。对于此规范,该值为 0
merchantInfo MerchantInfo 必需 请求付款数据的商家的相关信息。
allowedPaymentMethods PaymentMethod[] 必需 指定是否支持 Google Pay API 所支持的一种或多种付款方式。
transactionInfo TransactionInfo 必需 有关根据用户是否同意交易来为交易授权的详细信息。包含总价和价格状态。
callbackIntents 字符串[] 可选 PaymentDataCallbacks 指定以下回调 intent:
  • PAYMENT_AUTHORIZATION
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION
emailRequired 布尔值 可选 设为 true 可请求电子邮件地址。
shippingAddressRequired 布尔值 可选 设为 true 可请求完整的送货地址。
shippingAddressParameters ShippingAddressParameters 可选 如果 shippingAddressRequired 设为 true,请指定送货地址限制。
shippingOptionRequired 布尔值 可选 使用 SHIPPING_OPTION 回调 Intent 时,可设置为 true。如果您要实现对“授权付款”或“动态价格更新”的支持,则必须使用此字段。如需了解详情,请参阅 ShippingOptionParameters
shippingOptionParameters ShippingOptionParameters[] 可选 设置默认选项。

示例

以下示例显示了如何为所有受支持的支付卡网络的支付卡和 Android 设备令牌提供支持。系统会将支付卡令牌化,以用于示例网关。该请求针对付款方式发出,以收取 12.34 美元的最终费用。

{
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "merchantInfo": {
    "merchantName": "Example Merchant"
  },
  "allowedPaymentMethods": [
    {
      "type": "CARD",
      "parameters": {
        "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
        "allowedCardNetworks": ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"]
      },
      "tokenizationSpecification": {
        "type": "PAYMENT_GATEWAY",
        "parameters": {
          "gateway": "example",
          "gatewayMerchantId": "exampleGatewayMerchantId"
        }
      }
    }
  ],
  "transactionInfo": {
    "totalPriceStatus": "FINAL",
    "totalPrice": "12.34",
    "currencyCode": "USD"
  }
}

PaymentDataCallbacks

如果您在集成中设置了动态价格更新,请务必添加以下 onPaymentDataChangedonPaymentAuthorized 回调:

属性 类型 必要性 说明
onPaymentDataChanged 函数 可选 PaymentDataRequest 中设置以下 callbackIntents 值时调用:
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION
onPaymentAuthorized 函数 必需 PaymentDataRequest 中设置以下 callbackIntents 值时调用:PAYMENT_AUTHORIZATION

示例

以下示例配置使用了设置动态价格更新所需的回调:

{
  onPaymentDataChanged: onPaymentDataChanged,
  onPaymentAuthorized: onPaymentAuthorized
}

PaymentDataRequestUpdate

此对象可指定新的交易信息、运费选项和错误以更新付款表格。

属性 类型 必要性 说明
newTransactionInfo TransactionInfo 可选 更新付款表格中的交易信息。
newShippingOptionParameters ShippingOptionParameters 可选 更新付款表格中的运费选项。
error PaymentDataError 可选 向付款表格添加错误消息。

示例

以下示例显示了可返回到 Google Pay API 的所有付款数据请求更新。

{
  newTransactionInfo: {
   	displayItems: [
    {
      label: "Subtotal",
      type: "SUBTOTAL",
      price: "11.00",
    },
    {
      label: "Tax",
      type: "TAX",
      price: "1.00",
    }
  ],
  currencyCode: "USD",
  totalPriceStatus: "FINAL",
  totalPrice: "12.00",
  totalPriceLabel: "Total"
  },
  newShippingOptions: {
    defaultSelectedOptionId: "shipping-001",
    shippingOptions: [
      {
        "id": "shipping-001",
        "label": "Free: Standard shipping",
        "description": "Free Shipping delivered in 5 business days."
      }
    ]
  },
  error: {
    reason: "SHIPPING_ADDRESS_UNSERVICEABLE",
    message: "Cannot ship to the selected address",
    intent: "SHIPPING_ADDRESS"
  }
}

MerchantInfo

此对象可提供请求付款数据的商家的相关信息。

属性 类型 必要性 说明
merchantId 字符串 必需 Google 商家 ID,在您的网站取得 Google 批准后签发。如果在 environment 属性为 PRODUCTION 的情况下初始化 PaymentsClient,则为必需属性。如需详细了解审批流程以及如何获取 Google 商家标识符,请参阅集成核对清单
merchantName 字符串 可选 采用 UTF-8 编码的商家名称。商家名称会显示在付款表格中。若处于 TEST 环境,或者无法识别商家,系统会在付款表格中显示“向未经验证的商家付款”消息。
merchantOrigin 字符串 可选

以其商家名义发出请求的提供商的完全限定域名。如果网站提供 Google Pay 付款按钮并以其他网站名义请求付款信息(通常是通过托管结帐集成),则为必需属性。

示例

以下示例显示了包含 merchantInfomerchantNamemerchantId 对象。

merchantInfo: {
    merchantName: "Example Merchant",
    merchantId: "01234567890123456789"
}

PaymentMethod

此对象可指定 Google Pay API 支持且您的网站接受的一种或多种付款方式。

属性 类型 必要性 说明
type 字符串 必需

所支持付款方式的短标识符。目前仅支持 CARDPAYPAL 条目。

parameters 对象 必需 配置所提供的付款方式类型时所需的参数。如需详细了解 CARD 付款方式的预期值,请参阅 CardParameters。如需详细了解 PAYPAL 付款方式的预期值,请参阅 PAYPALParameters
tokenizationSpecification PaymentMethodTokenizationSpecification 可选

配置要接收付款信息的帐号或解密提供商。

如为 CARD 付款方式,则为必需属性。

如果此属性包含在 IsReadyToPayRequest 内,则不会产生任何影响。

以下示例显示了如何为所有受支持的支付卡网络的支付卡和 Android 设备令牌提供支持。此示例通过示例网关显示了令牌化过程。

{
  "type": "CARD",
  "parameters": {
    "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
    "allowedCardNetworks": ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"]
  },
  "tokenizationSpecification": {
    "type": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "example",
      "gatewayMerchantId": "exampleGatewayMerchantId"
    }
  }
}
PayPal

以下示例显示了如何支持 PAYPAL 付款方式。

{
  “type”: “PAYPAL”,
  parameters: {
  	"purchase_context": {
    	     "purchase_units": [{
        		"payee": {
          		      "merchant_id": "PAYPAL_ACCOUNT_ID"
                      	   }
       	       } ]
  	  }
    },
   “tokenizationSpecification”: {
	type: “DIRECT”  }
}

TokenizationSpecification

借助此对象,您可以配置要接收可扣款付款信息的帐号。

属性 类型 必要性 说明
type 字符串 必需

对于给定的 PaymentMethod,支持付款方式令牌化类型。对于 CARD 付款方式,请使用 PAYMENT_GATEWAYDIRECT。对于 PAYPAL PaymentMethod,请使用不带任何参数的 DIRECT

parameters 对象 必需 所选付款方式令牌化类型所特有的参数。

网关

type 设置为 PAYMENT_GATEWAY 可从 Google Pay API 支持的支付网关检索付款和客户信息。请按照网关的说明指定 parameters 属性。常见的属性包括由 Google 签发的网关标识符以及由您的网关提供的网关帐号 ID。

// [START EXAMPLE]
Example
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "example",
"gatewayMerchantId": "exampleGatewayMerchantId"  }
}
// [END EXAMPLE] // [START ACI]
ACI
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "aciworldwide",
 "gatewayMerchantId": "YOUR_ENTITY_ID"   }
}
// [END ACI] // [START ADYEN]
Adyen
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "adyen",
 "gatewayMerchantId": "YOUR_MERCHANT_ACCOUNT_NAME"   }
}
// [END ADYEN] // [START ALFA-BANK]
Alfa-Bank
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "alfabank",
 "gatewayMerchantId ":"YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END ALFA-BANK] // [START BLUE_MEDIA]
Blue Media
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "bluemedia",
 "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"   }
}
// [END BLUE_MEDIA] // [START BLUESNAP]
BlueSnap
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "bluesnap",
 "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"   }
}
// [END BLUESNAP] // [START BRAINTREE]
Braintree
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "braintree",
"braintree:apiVersion": "v1", "braintree:sdkVersion": braintree.client.VERSION, "braintree:merchantId": "YOUR_BRAINTREE_MERCHANT_ID", "braintree:clientKey": "YOUR_BRAINTREE_TOKENIZATION_KEY"   }
}
// [END BRAINTREE] // [START BRASPAG]
Braspag
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "cielo",
 "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"   }
}
// [END BRASPAG] // [START CARDCONNECT]
CardConnect
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "cardconnect",
 "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"   }
}
// [END CARDCONNECT] // [START CHASE_PAYMENTECH]
Chase Paymentech
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "chase",
 "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ACCOUNT_NUMBER"   }
}
// [END CHASE_PAYMENTECH] // [START CHECKOUT]
Checkout.com
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "checkoutltd",
 "gatewayMerchantId": "YOUR_PUBLIC_KEY"   }
}
// [END CHECKOUT] // [START CLOUDPAYMENTS]
CloudPayments
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "cloudpayments",
 "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"   }
}
// [END CLOUDPAYMENTS] // [START CYBERSOURCE]
CyberSource
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "cybersource",
 "gatewayMerchantId": "YOUR_MERCHANT_ID"   }
}
// [END CYBERSOURCE] // [START DATATRANS]
Datatrans
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "datatrans",
"gatewayMerchantId": "YOUR_MERCHANT_ID"  }
}
// [END DATATRANS] // [START EBANX]
EBANX
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "ebanx",
    "gatewayMerchantId": "YOUR_PUBLIC_INTEGRATION_KEY"   }
}
// [END EBANX] // [START FIRST_DATA]
First Data
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "firstdata",
    "gatewayMerchantId": "YOUR_MERCHANT_ID"   }
}
// [END FIRST_DATA] // [START GLOBAL_PAYMENTS]
Global Payments
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "globalpayments",
"gatewayMerchantId": "YOUR_MERCHANT_ID"  }
}
// [END GLOBAL_PAYMENTS] // [START GOPAY]
GoPay
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "gopay",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END GOPAY] // [START GMO_PAYMENT_GATEWAY]
GMO Payment Gateway
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "gmopg",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END GMO_PAYMENT_GATEWAY] // [START HITRUST]
HiTrust
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "hitrustpay",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END HITRUST] // [START IMSOLUTIONS]
IMSolutions
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "imsolutions",
"gatewayMerchantId": "YOUR_MERCHANT_ID"  }
}
// [END IMSOLUTIONS] // [START IQMETRIX]
iQmetrix
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "iqmetrixpaymentservicesgateway",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END IQMETRIX] // [START LYRA]
Lyra
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "lyra",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END LYRA] // [START MPGS]
MPGS
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "mpgs",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END MPGS] // [START MONEY_MAIL_RU]
Money.Mail.Ru
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "moneymailru",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END MONEY_MAIL_RU] // [START MUNDIPAGG]
Mundipagg
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "mundipagg",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END MUNDIPAGG] // [START NEWEBPAY]
Newebpay
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "newebpay",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END NEWEBPAY] // [START NEXI]
Nexi
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "nexi",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END NEXI] // [START NMI]
NMI
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "creditcall",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END NMI] // [START PAYSAFE]
Paysafe
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "paysafe",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END PAYSAFE] // [START PAYTURE]
Payture
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "payture",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END PAYTURE] // [START PAYU]
PayU
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "payu",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END PAYU] // [START PRZELEWY24]
Przelewy24
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "przelewy24",
"gatewayMerchantId": "YOUR_MERCHANT_ID"  }
}
// [END PRZELEWY24] // [START RBKMONEY]
RBKmoney
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "rbkmoney",
"gatewayMerchantId": "YOUR_MERCHANT_ID"  }
}
// [END RBKMONEY] // [START REDSYS]
Redsys
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "redsys",
    "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END REDSYS] // [START SBERBANK]
Sberbank
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "sberbank",
"gatewayMerchantId": "YOUR_ORGANIZATION_NAME"  }
}
// [END SBERBANK] // [START SOFTBANK_PAYMENT_SERVICE]
Softbank Payment Service
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "sbps",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END SOFTBANK_PAYMENT_SERVICE] // [START SONY_PAYMENT_SERVICES]
Sony Payment Services
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "sonypaymentservices",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END SONY_PAYMENT_SERVICES]// [START SQUARE]
Square
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "square",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END SQUARE] // [START STRIPE]
Stripe
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "stripe",
"stripe:version": "2018-10-31", "stripe:publishableKey": "YOUR_PUBLIC_STRIPE_KEY"  }
}
// [END STRIPE] // [START TAPPAY]
TapPay
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "tappay",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END TAPPAY] // [START TINKOFF]
Tinkoff
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "tinkoff",
 "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END TINKOFF] // [START UNITELLER]
Uniteller
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "uniteller",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END UNITELLER] // [START VANTIV]
Vantiv
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "vantiv",
"vantiv:merchantPayPageId": "YOUR_PAY_PAGE_ID", "vantiv:merchantOrderId": "YOUR_ORDER_ID", "vantiv:merchantTransactionId": "YOUR_TRANSACTION_ID", "vantiv:merchantReportGroup": "*web"  }
}
// [END VANTIV] // [START VERITRANS]
Veritrans
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "veritrans",
    "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END VERITRANS] // [START VINDICIA]
Vindicia
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "vindicia",
"gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"  }
}
// [END VINDICIA] // [START WORLDPAY]
Worldpay
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "worldpay",
"gatewayMerchantId": "YOUR_WORLDPAY_MERCHANT_ID"  }
}
// [END WORLDPAY] // [START YANDEX]
Yandex
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "yandexcheckout",
"gatewayMerchantId": "YOUR_SHOP_ID"  }
}
// [END YANDEX]

Direct

type 设置为 DIRECT 可直接在您的服务器上解密响应。此配置需要满足 Google 额外的数据安全要求,并会增加符合 PCI DSS 规定的复杂度。

属性 类型 必要性 说明
protocolVersion 字符串 必需 在响应中显示的加密/签名协议版本。目前支持 ECv2。如需详细了解可用的加密和签名协议,请参阅付款数据加密
publicKey 字符串 必需 采用 Base64 编码的椭圆曲线公钥。如需了解详情,请参阅我们的商家加密文档中的加密公钥格式部分。
示例

在以下示例中,publicKey 值采用了缩写形式,以方便阅读。

"tokenizationSpecification": {
  "type": "DIRECT",
  "parameters": {
    "protocolVersion": "ECv2",
    "publicKey": "BOdoXP1aiNp.....kh3JUhiSZKHYF2Y="
  }
}

CardParameters

借助此对象,您可以定义所接受的支付卡类型。Google 会根据您配置的选项过滤付款人的可用支付卡。

属性 类型 必要性 说明
allowedAuthMethods 字符串[] 必需

支持用于对卡交易进行身份验证的字段。

  • PAN_ONLY:此身份验证方法与用户的 Google 帐号中保存的支付卡相关联。返回的付款数据包含个人帐号 (PAN) 以及到期月份和到期年份。
  • CRYPTOGRAM_3DS:此身份验证方法与存储为 Android 设备令牌的卡相关联。返回的付款数据包括在设备上生成的 3D 安全 (3DS) 密文。
allowedCardNetworks 字符串 必需

您和 Google Pay API 都支持的一个或多个支付卡网络。

  • AMEX
  • DISCOVER
  • INTERAC
  • JCB
  • MASTERCARD
  • VISA
allowPrepaidCards 布尔值 可选 如果您不支持预付卡,请将此属性设为 false。默认情况:指定的支付卡网络支持预付卡类。
billingAddressRequired 布尔值 可选 如果您要求提供帐单邮寄地址,请将此属性设为 true。请仅在必须提供帐单邮寄地址才能处理交易的情况下,请求帐单邮寄地址。额外的数据请求会使结算流程不能顺畅进行,并可能会导致转化率较低。
billingAddressParameters BillingAddressParameters 可选 如果 billingAddressRequired 设为 true,则返回预期字段。

CARD 示例

以下示例显示了如何支持所有可用的支付卡网络和卡身份验证方法:

{
  "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
  "allowedCardNetworks": ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"]
}

BillingAddressParameters

此对象可让您设置要为所请求的帐单邮寄地址返回的其他字段。

属性 类型 必要性 说明
format 字符串 可选

完成交易所需的帐单邮寄地址格式。

  • MIN:名字、国家/地区代码和邮政编码(默认)。
  • FULL:名字、街道地址、市行政区、区域、国家/地区代码和邮政编码。
phoneNumberRequired 布尔值 可选 如果必须提供电话号码才能处理交易,请将此属性设为 true

示例

以下示例显示了如何请求最基本的帐单邮寄地址,即属性当前的默认值。

{
  "format": "MIN"
}

ShippingAddressParameters

此对象可用于设置送货限制。

属性 类型 必要性 说明
allowedCountryCodes 字符串[] 可选 允许送货的国家/地区的 ISO 3166-1 alpha-2 国家/地区代码值。如果未指定此对象,就意味着支持所有送货国家/地区。
phoneNumberRequired 布尔值 可选 如果所提供的送货地址需要填写电话号码,请将此属性设为 true

示例

以下示例是针对美国送货地址的请求。

{
  "allowedCountryCodes": ["US"]
}

ShippingOptionParameters

属性 类型 必要性 说明
shippingOptions SelectionOption 必需 适用于当前请求的所有运费选项。
defaultSelectedOptionId 字符串 可选 所选的默认运费选项的标识符。如果未提供此字段的值,那么第一个选项是默认选项。

示例

以下示例显示了付款表格的所有运费选项以及默认的运费选项。

{
  defaultSelectedOptionId: "0",
  shippingOptions: [
    {
      "id": "shipping-001",
      "label": "$0.00: Free shipping",
      "description": "Free Shipping delivered in 5 business days."
    },
    {
      "id": "shipping-002",
      "label": "$1.99: Standard shipping",
      "description": "Standard shipping delivered in 3 business days."
    },
    {
      "id": "shipping-003",
      "label": "$1000: Express shipping",
      "description": "Express shipping delivered in 1 business day."
    }
  ]
}

SelectionOption

属性 类型 必要性 说明
id 字符串 必需 开发者可将需要返回的任何值放在 PaymentData 中。
label 字符串 必需 要显示为选项的标签。
description 字符串 可选 显示在选项标签下方的描述性文本。

示例

以下示例显示了一个运费选项。

{
  "id": "shipping-003",
  "label": "$10: Express shipping",
  "description": "Express shipping delivered in 1 business day."
}

TransactionInfo

此对象描述了一个用于确定付款人是否能付款的交易。它用于显示付款授权对话框。

属性 类型 必要性 说明
currencyCode 字符串 必需 ISO 4217 字母货币代码。
totalPriceStatus 字符串 必需

所用总价的状态:

  • NOT_CURRENTLY_KNOWN:用于付款能力检查。
  • ESTIMATED:总价可能会根据响应详细信息(例如根据帐单邮寄地址收取的销售税)进行调整。
  • FINAL:总价与显示给买家的金额相比无变化。
totalPrice 字符串 可选

交易的总货币价值,可选择是否精确到小数点后两位。除非将 totalPriceStatus 设置为NOT_CURRENTLY_KNOWN,否则此字段是必填字段。

字符串的格式应遵循正则表达式格式:^[0-9]+(\.[0-9][0-9])?$

displayItems DisplayItem[] 可选 当前付款请求的所有可扣费用。如果您使用授权付款动态价格更新,则仅在付款表格中填充此内容。
totalPriceLabel 字符串 可选 显示项范围内总价的自定义标签。
checkoutOption 字符串 可选

此属性会影响在 Google Pay 付款表格中显示的提交按钮文本。

  • DEFAULT:对于给定的 totalPriceStatus,适用标准文本(默认值)。
  • COMPLETE_IMMEDIATE_PURCHASE:在付款人确认其选择后,系统会立即通过所选付款方式扣费。只有当 totalPriceStatus 设为 FINAL 时,才可使用此选项。

示例

以下示例显示了以美元表示的最终价格。

{
  displayItems: [
    {
      label: "Subtotal",
      type: "SUBTOTAL",
      price: "11.00",
    },
    {
      label: "Tax",
      type: "TAX",
      price: "1.00",
    }
  ],
    currencyCode: "USD",
    totalPriceStatus: "FINAL",
    totalPrice: "12.00",
    totalPriceLabel: "Total",
    checkoutOption: "DEFAULT",
    newShippingOptions: {
 	    defaultSelectedOptionId: "shipping-001",
      shippingOptions: [
        {
          "id": "shipping-001",
          "label": "Free: Standard shipping",
          "description": "Free Shipping delivered in 5 business days."
        }
      ]
    },
    error: {
   	  reason: "SHIPPING_ADDRESS_UNSERVICEABLE",
      message: "Cannot ship to the selected address",
      intent: "SHIPPING_ADDRESS"
    }
}

ButtonOptions

此对象可让您配置 Google Pay 付款按钮。要详细了解按钮类型、颜色和显示要求,请参阅 Google 的品牌推广指南

属性 类型 必要性 说明
onClick

functionObject

必需 要在点击事件传送到 <button> 目标时调用的事件监听器回调
buttonColor 字符串 可选
  • default:Google 选择的默认值。目前为 black,但可能会随时间而变化(默认)。
  • black:适合在白色或浅色背景上使用的黑色按钮。
  • white:适合在彩色背景上使用的白色按钮。
buttonType 字符串 可选
  • long:“使用 Google Pay 付款”按钮(默认)。如果查看者浏览器中指定的语言与可用语言相符,系统可能会显示已翻译的按钮标签。
  • short:不带“Buy with”文字的 Google Pay 付款按钮。

PayPalParameters

借助此对象,您可以定义 PayPal 参数。

属性 类型 必要性 说明
purchase_context PurchaseContext 必需 使用订单相关信息作为说明。

PayPal 示例

以下示例显示了如何支持 PayPal 付款方式:

{
  "purchase_context": {
    "purchase_units": [
      {
        "payee": {
          "merchant_id": "PAYPAL_ACCOUNT_ID"
        }
      }
    ]
  }
}

PurchaseContext

此对象可提供与订单有关的信息。

属性 类型 必要性 说明
purchase_units PurchaseUnit[] 必需 描述客户与商家之间的合约。

PurchaseUnit

此对象描述了 PayPal 客户与 PayPal 商家之间的合约。如需了解详情,请参阅 PayPal Order API 文档中的 purchase_unit

属性 类型 必要性 说明
payee Payee 必需 此交易的资金收据。

Payee

此对象可提供接收资金的商家的相关信息。如需了解详情,请参阅 PayPal Order API 参考文档中的 payee 参数。

对于其他支持的参数,请参阅可选参数

PayPal 示例

以下示例显示了如何支持 PayPal 付款方式。

{
  “type”: “PAYPAL”,
  parameters: {
  	"purchase_context": {
    	     "purchase_units": [{
        		"payee": {
          		      "merchant_id": "PAYPAL_ACCOUNT_ID"
                      	   }
       	       } ]
  	  }
    },
   “tokenizationSpecification”: {
	type: “DIRECT”  }
}

示例

此示例会生成一个 Google Pay 付款按钮,其中包含点击事件处理脚本和默认显示选项。

{
  onClick: onGooglePaymentButtonClicked
}

响应对象

响应对象是由 Google Pay API 客户端方法返回的对象。

IsReadyToPayResponse

此对象提供了有关网站访问者能否向提出请求的网站提供付款信息的信息。

属性 类型 是否始终存在 说明
result 布尔值 当前访问者能够向提出请求的网站提供付款信息。访问者能否付款可能与他们的网络浏览器能否显示指定付款方式所需的组件有关。这包括他们登录 Google 帐号并提供付款方式的时间。
paymentMethodPresent 布尔值

如果为 true,则访问者具有提供的 IsReadyToPayRequestallowedPaymentMethods 属性中指定的一种或多种付款方式。

仅当 existingPaymentMethodRequiredIsReadyToPayRequest 中设为 true 时才存在。

如果使用 TESTenvironment 属性初始化 PaymentsClient,则系统始终认为存在某种付款方式。

示例

以下示例显示了当前访问者何时能够向提出请求的网站提供付款信息。

{
  "result": true
}

PaymentData

此为 Google 在付款人批准付款后返回的响应对象。

属性 类型 是否始终存在 说明
apiVersion 数值 主要 API 版本。响应中的值与 PaymentDataRequest 中提供的值一致。
apiVersionMinor 数值 次要 API 版本。响应中的值与 PaymentDataRequest 中提供的值一致。
paymentMethodData PaymentMethodData 所选付款方式的相关数据。
email 字符串 如果 emailRequiredPaymentDataRequest 中设为 true,则此属性的值为电子邮件地址。如果另一个请求将此属性设置为 true,则不会产生任何影响。
shippingAddress 地址 如果 shippingAddressRequiredPaymentDataRequest 中设为 true,则此属性的值为送货地址。

示例

针对 Google Pay API 版本 2.0 的此示例响应显示了在 Google Pay 付款表格中选择的 CARD 付款方式,并为 example 网关生成了付款方式令牌。

{
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "paymentMethodData": {
    "type": "CARD",
    "description": "Visa •••• 1234",
    "info": {
      "cardNetwork": "VISA",
      "cardDetails": "1234"
    },
    "tokenizationData": {
      "type": "PAYMENT_GATEWAY",
      "token": "examplePaymentMethodToken"
    }
  }
}

IntermediatePaymentData

如果在付款表格中更改了送货地址或运费选项,则 Google Pay API onPaymentDataChanged() 输入会返回此对象。

属性 类型 必要性 说明
callbackTrigger 字符串 可选

说明付款数据回调函数被调用的原因。

  • INITIALIZE
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION
shippingAddress IntermediateAddress 可选 在付款表格中选择的地址。
shippingOptionData SelectionOptionData 可选 在付款表格中选择的运费选项。

示例

此示例显示了从 Google Pay API 返回的中间负载。

{
  callbackTrigger: "SHIPPING_ADDRESS"
  shippingAddress: {
    administrativeArea: "NY"
    countryCode: "US"
    locality: "New York"
    postalCode: "10011"
  },
  shippingOptionData: {
    id: "shipping-001"
  }
}

PaymentMethodData

此对象可为所选付款方式提供数据。

属性 类型 是否始终存在 说明
type 字符串 在 Google Pay 付款表格中选择的 PaymentMethod type
description 字符串

面向用户的消息,用于说明此交易所使用的付款方式。

info 对象 此属性的值取决于所返回的付款方式 type。如需了解 CARD,请参阅 CardInfo
tokenizationData PaymentMethodTokenizationData 所选付款方式的付款令牌化数据。

示例

此示例响应显示了在 Google Pay 付款表格中选择的 CARD 付款方式如何为 example 网关生成付款方式令牌。

{
  "type": "CARD",
  "description": "Visa •••• 1234",
  "info": {
    "cardNetwork": "VISA",
    "cardDetails": "1234"
  },
  "tokenizationData": {
    "type": "PAYMENT_GATEWAY",
    "token": "examplePaymentMethodToken"
  }
}

CardInfo

此对象可提供所选支付卡的相关信息。

属性 类型 是否始终存在 说明
cardDetails 字符串 支付卡的详细信息。此值通常是所选付款帐号的后四位数。
cardNetwork 字符串

所选款项的支付卡网络。返回的值与 allowedCardNetworks 中的 allowedCardNetworks 格式一致。

此支付卡网络值不应向买家显示。但可在需要买家支付卡的详细信息时使用。例如,客户服务人员可使用此值来确定买家为其交易所使用的卡。若要向用户显示相关说明,请使用 PaymentMethodDatadescription 属性。

billingAddress 地址 与所提供付款方式相关联的帐单邮寄地址(如果在 CardParameters 中将 billingAddressRequired 设为 true)。

示例

此示例显示了 Visa 网络中的卡。

{
  "cardNetwork": "VISA",
  "cardDetails": "1234"
}

PaymentMethodTokenizationData

此对象可提供付款方式的令牌化数据。

属性 类型 是否始终存在 说明
type 字符串 要应用于所选付款方式的令牌化类型。此值与 PaymentMethodTokenizationSpecification 中设置的 type 一致。
token 字符串

生成的付款方式令牌。

  • PAYMENT_GATEWAY:JSON 对象字符串,其中包含由您的网关签发的可扣款令牌。
  • DIRECTprotocolVersionsignaturesignedMessage,可用于解密。如需了解详情,请参阅付款方式令牌结构

示例

此示例显示了为 example 网关准备的令牌化响应。

{
  "type": "PAYMENT_GATEWAY",
  "token": "examplePaymentMethodToken"
}

DisplayItem

属性 类型 必要性 说明
label 字符串 必需 要为指定选项显示的标签。
type 字符串 必需

显示的订单项的类型:

  • LINE_ITEM
  • SUBTOTAL
price 字符串 必需 购物车商品的货币价值,可选择是否精确到小数点后两位。允许为负值。
status 字符串 可选

以下变量定义了差价:

  • FINAL
  • PENDING

如果未提供,则默认为 FINAL

示例

此示例显示了可以在付款表格中显示的交易项列表。

{
  displayItems: [
    {
      label: "Subtotal",
      type: "SUBTOTAL",
      price: "11.00",
    },
    {
      label: "Tax",
      type: "TAX",
      price: "1.00",
    },
    {
      "label": "Shipping",
      "type": "LINE_ITEM",
      "price": "0", // Won't be displayed since status is PENDING
      "status": "PENDING",
    }
  ]
}

PaymentAuthorizationResult

此对象可提供付款授权结果的相关信息。

属性 类型 必要性 说明
transactionState 字符串 必需 交易状态可根据以下某个商家结果解析:
  • SUCCESS
  • ERROR
error PaymentDataError 可选 当需要重试付款时,在用户的付款表格中呈现的错误。

示例

以下示例显示了处理付款后的付款结果返回值:

{
  transactionState: "ERROR",
  error: {
    reason: "PAYMENT_DATA_INVALID",
    message: "Cannot pay with payment credentials",
    intent: "PAYMENT_AUTHORIZATION"
  }
}

PaymentDataError

属性 类型 必要性 说明
reason 字符串 必需

预定义的错误原因列表:

  • PAYMENT_DATA_INVALID
  • SHIPPING_ADDRESS_INVALID
  • SHIPPING_ADDRESS_UNSERVICEABLE
  • SHIPPING_OPTION_INVALID
  • OTHER_ERROR
message 字符串 必需 用户在对话框中看到的错误消息。
intent 字符串 必需

错误的用意。从流程一开始,此属性就必须已在 PaymentDataRequest 中注册。

  • PAYMENT_AUTHORIZATION
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION

示例

此示例显示了要在付款表格中呈现的错误 intent 和消息。

{
  error: {
    reason: "SHIPPING_OPTION_INVALID",
    message: "This shipping option is invalid for the given address",
    intent: "SHIPPING_OPTION"
  }
}

地址

此对象可提供所请求邮政地址的相关信息。所有属性均为字符串。

如果 billingAddressFormat 设为 MIN,系统可能会返回 MIN 地址格式。送货地址会以 FULL 地址格式返回。MIN 格式的响应中的所有属性都存在于 FULL 格式的响应中。

属性 地址格式 说明
name MIN 收件人的全名。
postalCode MIN 邮政编码。
countryCode MIN ISO 3166-1 alpha-2 国家/地区代码。
phoneNumber MIN 如果 phoneNumberRequiredPaymentDataRequest 中设为 true,则此属性的值为电话号码。
address1 FULL 地址的第一行。
address2 FULL 地址的第二行。
address3 FULL 地址的第三行。
locality FULL 城市、城镇、社区或郊区。
administrativeArea FULL 国家/地区行政区,例如州或省。
sortingCode FULL 分拣编码

示例

此示例显示了一个包含多行街道地址数据的美国地址。

{
  "name": "John Doe",
  "address1": "c/o Google LLC",
  "address2": "1600 Amphitheatre Pkwy",
  "address3": "Building 40",
  "locality": "Mountain View",
  "administrativeArea": "CA",
  "countryCode": "US",
  "postalCode": "94043",
  "sortingCode": ""
}

IntermediateAddress

属性 类型 必要性 说明
administrativeArea 字符串 必需 国家/地区行政区,例如州或省。
countryCode 字符串 必需 ISO 3166-1 alpha-2 国家/地区代码。
locality 字符串 必需 城市、城镇、社区或郊区。
postalCode 字符串 必需 基于国家/地区的已遮盖邮政编码。对于加拿大和英国,此编码仅包含前三个字符。对于美国,此编码包含前 5 位数字。

示例

此示例显示了您在付款表格中选择的地址。

{
  administrativeArea: "NY",
  countryCode: "US",
  locality: "New York",
  postalCode: "10011"
}

SelectionOptionData

属性 类型 必要性 说明
id 字符串 必需 SelectionOption.id 一致

示例

此示例显示了在付款表格中选择的运费选项。

{
  id: "shipping-001"
}

错误对象

错误对象是由客户端 JavaScript 方法中被拒绝的承诺返回的对象。

PaymentsError

此对象包含有关由客户端 JavaScript 方法返回的错误的详细信息。面向用户的对话框中可能不会显示相关错误。

属性 类型 说明
statusCode 字符串 用于描述错误类型的简短代码。
statusMessage 字符串 面向开发者的消息,用于描述遇到的错误以及用以纠正该错误的可能步骤。

常见错误

此对象显示了您在所有 JavaScript 方法中可能会遇到的错误。请务必查看开发者控制台,以了解其他错误消息。

状态代码 说明
BUYER_ACCOUNT_ERROR 当前的 Google 用户无法提供付款信息。
DEVELOPER_ERROR

传递的参数格式不正确。对于所有已配置的环境,浏览器控制台中可能会显示错误消息

MERCHANT_ACCOUNT_ERROR

访问 Google Pay API 的网站没有相应权限。这可能是由于配置不正确或请求中设置的商家 ID 不正确。请查看 statusMessage 字段了解详情。如果您仍有问题,请与支持人员联系

INTERNAL_ERROR 常规服务器错误。