Google Pay PAN_ONLY 检查

Google Pay PAN_ONLY 检查接口允许商户在处理支付前确定 Google Pay 令牌是否需要收集 CVV。该接口分析 Google Pay 加密令牌并返回支付方式是否处于 PAN_ONLY 模式。

集成前置条件

在实施 Google Pay PAN_ONLY 检查之前，请确保您具备：

有效的 Google Pay 商户账户，且已启用令牌处理
已在您的网站或应用程序上实现 Google Pay 集成
可访问 Onerway 支付网关 API
来自客户支付授权的 Google Pay 加密令牌
具备处理条件性 CVV 收集流程的技术能力

Google Pay PAN_ONLY 检查优势

此 API 对于 Google Pay 集成优化至关重要：

CVV 收集优化：确定 Google Pay 交易是否需要收集 CVV
结账流程增强：根据令牌分析条件性显示 CVV 输入字段
合规保证：确保符合 Google Pay 支付处理要求
用户体验：通过避免不必要的 CVV 请求减少摩擦
支付成功率：通过提供所需的认证数据提高授权率

接口请求参数

POST

注意

所有 JSON 字段必须在提交前进行字符串化处理
嵌套对象必须序列化为 JSON 字符串格式
JSON 字段不能包含未转义的特殊字符
JSON 中的数组应该正确格式化
JSON 字符串字段示例：

json

{
  "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
  "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}

Parameter	Type	Length	Required	Signed	Description
appId	String	20	Yes	Yes	Merchant application ID assigned by Onerway for website identification.
gatewayName	String	64	Yes	Yes	Payment gateway identifier for Google Pay token processing.
merchantNo	String	20	Yes	Yes	Merchant number assigned by `Onerway` upon registration, obtained from the `Onerway` merchant dashboard.
merchantTxnId	String	64	Yes	Yes	Unique transaction identifier for each customer payment, generated by the merchant system.
sign	String	/	Yes	No	Digital signature string for request verification and security. Please refer to Signature for signature generation method.
tokenInfoJson	String	/	Yes	Yes	Serialized tokenInfo structure as JSON string for checking Google Pay PAN_ONLY mode. See TokenInfo for structure details.

响应

Name	Type	Description
respCode	String	Response code from `Onerway`
respMsg	String	Response message from `Onerway`
data	Object	Response data. Refer to object data

data

Name	Type	Description
└─ cardNum	String	Masked card number extracted from Google Pay token.
└─ checkResult	Boolean	PAN_ONLY mode check result. `true` means CVV collection is required, `false` means no CVV needed.

集成流程

接口使用示例

请求响应 - PAN_ONLY 模式响应 - 标准模式

json

{
    "appId": "1727880846378401792",
    "gatewayName": "ronghan",
    "merchantNo": "800209",
    "merchantTxnId": "07f6d404-0de4-45fb-b80d-df47815422b4",
    "sign": "14d4b20492692820c39944ad6b63d871161da4b2c9ee15a106565c74fe85fbad",
    "tokenInfoJson": "{\"provider\":\"GooglePay\",\"tokenId\":\"{\\\"signature\\\":\\\"MEYCIQCvwmUnXStC/Qhdv6XQxe5xu3yiOCXYMpEp9tzdeHcQmgIhAOHakh9S47uHSPoObcSjHhIlQncEv+1oRkVY9zoYrYP7\\\",\\\"intermediateSigningKey\\\":{\\\"signedKey\\\":\\\"{\\\\\\\"keyValue\\\\\\\":\\\\\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE+F0IUGuqIge8NpRKXdhF+mHIu90N1X+uLJ0KuiYgqtMCNU/xQyn7FfeMUuIeLFFoFoRr/rvK/y3EtZUpTqjo5A\\\\\\\\u003d\\\\\\\\u003d\\\\\\\",\\\\\\\"keyExpiration\\\\\\\":\\\\\\\"1752655434646\\\\\\\"}\\\",\\\"signatures\\\":[\\\"MEQCID26+6e9vq0IHaWT3ORBCYJVR2Sr6eCpIO7V9fbKnXodAiBcu5gBmT/qwFjTsuRKmRPYYQfmhj4HV0auXrmHaPCPTw==\\\"]},\\\"protocolVersion\\\":\\\"ECv2\\\",\\\"signedMessage\\\":\\\"{\\\\\\\"encryptedMessage\\\\\\\":\\\\\\\"LFCsimI+8uLb6tX1mn0/c63DbvdPqOlLq8fJCJ8MnsTwvvQmaVWnLVFDikH5cePDCLz/D7Y8bUVW+Bfz38qB5WpcHtQrRoIQB1JEVoOL6tnFcrmQ87OeIfq9zgzWUp4TUF9NNJwYUit+2mrUeUR8elxq0ulavtiefhi7K0oIIFemBI2BfrlpIb/YjEsMbaAOLiYL+FvVyVxYiWeeGbsc5gAv0KJ9HrTKSIoMJ2fWoV/aMdX3iNnWTijr5x77JqHUdkMeo5xu/AUiODzqVAUl2UPCj/met2MFQpbvOea0102WdzrsviXisFniG5LQuxHyqXbYuoYRJhnpdk0F0XBL0tUAjiMd9rsULeCBc6JhxGgH+XnYorVVdXNKO08ZrFTQ+ZdaLEsiM+SatwGDa+Pt2+v5nbAq3SPwI0SgNmRdbkiOxdSKd//ZaooR0IQPQ21EJQAtdfr4KfMN0wmqA81VFrSuUySK8sVukyFde/OL9Fa/T0rLi7fqccF0d8Udl+C9Z3xReeMb03UuO+YcLT8g8QrdtDqungfCcP11hpmfx6M5/pebvZ1vYNFi\\\\\\\",\\\\\\\"ephemeralPublicKey\\\\\\\":\\\\\\\"BHcjhYHhu2QxoIGui2b451KY0ISiwi6u1y33bR0BHzqipB8XDx6YPAiRHYPI9umvwM+Pd9jGyNWBvOvI8xXiFaE\\\\\\\\u003d\\\\\\\",\\\\\\\"tag\\\\\\\":\\\\\\\"Ntfma/N099yxBNEd3lwB8aOjQws+K07IYa2Djfm5OeQ\\\\\\\\u003d\\\\\\\"}\\\"}\"}"

}

json

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "cardNum": "411111******1111",
    "checkResult": true
  }
}

json

{
  "respCode": "20000", 
  "respMsg": "Success", 
  "data": {

    "cardNum": "411111******1111",
    "checkResult": false

  }
}

令牌支付示例

根据检查结果，使用以下接口进行实际的令牌支付。详细的接口文档请参考 Token支付。

POST

PAN_ONLY 令牌支付示例

当 checkResult 为 true 时，在令牌支付请求中包含 CVV：

json

{
    "billingInformation": "{\"address\":\"889 Mill Close\",\"city\":\"Buckridgefield\",\"country\":\"US\",\"email\":\"Ryan.Purdy@gmail.com\",\"firstName\":\"Frederik\",\"identityNumber\":\"92066033023\",\"lastName\":\"Pfannerstill\",\"phone\":\"15209608948\",\"postalCode\":\"96542\",\"province\":\"CO\"}",
    "cardInfo": "{\"cvv\":\"123\"}", 
    "merchantCustId": "CustId-75S6-256P",
    "merchantNo": "800209",
    "merchantTxnId": "9a8397cf-40af-4d88-ad5c-1961459f5319",
    "merchantTxnTime": "2025-06-25 20:18:57",
    "orderAmount": "1",
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"address\":\"72981 Alejandrin Port\",\"city\":\"Lake Judd\",\"country\":\"US\",\"email\":\"Tracy_Stanton58@gmail.com\",\"firstName\":\"Noble\",\"identityNumber\":\"84880795738\",\"lastName\":\"Baumbach\",\"phone\":\"18434119887\",\"postalCode\":\"12053\",\"province\":\"CO\"}",
    "sign": "a1c67b19bd0c6c7c5f7806d16c86e329225ac47a645df6d4e21ad2731decc932",
    "subProductType": "DIRECT",
    "tokenInfo": "{\"provider\":\"GooglePay\",\"tokenId\":\"{\\\"signature\\\":\\\"MEYCIQCvwmUnXStC/Qhdv6XQxe5xu3yiOCXYMpEp9tzdeHcQmgIhAOHakh9S47uHSPoObcSjHhIlQncEv+1oRkVY9zoYrYP7\\\",\\\"intermediateSigningKey\\\":{\\\"signedKey\\\":\\\"{\\\\\\\"keyValue\\\\\\\":\\\\\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE+F0IUGuqIge8NpRKXdhF+mHIu90N1X+uLJ0KuiYgqtMCNU/xQyn7FfeMUuIeLFFoFoRr/rvK/y3EtZUpTqjo5A\\\\\\\\u003d\\\\\\\\u003d\\\\\\\",\\\\\\\"keyExpiration\\\\\\\":\\\\\\\"1752655434646\\\\\\\"}\\\",\\\"signatures\\\":[\\\"MEQCID26+6e9vq0IHaWT3ORBCYJVR2Sr6eCpIO7V9fbKnXodAiBcu5gBmT/qwFjTsuRKmRPYYQfmhj4HV0auXrmHaPCPTw==\\\"]},\\\"protocolVersion\\\":\\\"ECv2\\\",\\\"signedMessage\\\":\\\"{\\\\\\\"encryptedMessage\\\\\\\":\\\\\\\"LFCsimI+8uLb6tX1mn0/c63DbvdPqOlLq8fJCJ8MnsTwvvQmaVWnLVFDikH5cePDCLz/D7Y8bUVW+Bfz38qB5WpcHtQrRoIQB1JEVoOL6tnFcrmQ87OeIfq9zgzWUp4TUF9NNJwYUit+2mrUeUR8elxq0ulavtiefhi7K0oIIFemBI2BfrlpIb/YjEsMbaAOLiYL+FvVyVxYiWeeGbsc5gAv0KJ9HrTKSIoMJ2fWoV/aMdX3iNnWTijr5x77JqHUdkMeo5xu/AUiODzqVAUl2UPCj/met2MFQpbvOea0102WdzrsviXisFniG5LQuxHyqXbYuoYRJhnpdk0F0XBL0tUAjiMd9rsULeCBc6JhxGgH+XnYorVVdXNKO08ZrFTQ+ZdaLEsiM+SatwGDa+Pt2+v5nbAq3SPwI0SgNmRdbkiOxdSKd//ZaooR0IQPQ21EJQAtdfr4KfMN0wmqA81VFrSuUySK8sVukyFde/OL9Fa/T0rLi7fqccF0d8Udl+C9Z3xReeMb03UuO+YcLT8g8QrdtDqungfCcP11hpmfx6M5/pebvZ1vYNFi\\\\\\\",\\\\\\\"ephemeralPublicKey\\\\\\\":\\\\\\\"BHcjhYHhu2QxoIGui2b451KY0ISiwi6u1y33bR0BHzqipB8XDx6YPAiRHYPI9umvwM+Pd9jGyNWBvOvI8xXiFaE\\\\\\\\u003d\\\\\\\",\\\\\\\"tag\\\\\\\":\\\\\\\"Ntfma/N099yxBNEd3lwB8aOjQws+K07IYa2Djfm5OeQ\\\\\\\\u003d\\\\\\\"}\\\"}\"}",
    "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"24\",\"contentLength\":\"65536\",\"javaEnabled\":false,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"butternut pumpkin\\\",\\\"num\\\":\\\"96\\\",\\\"price\\\":\\\"708.69\\\",\\\"type\\\":\\\"est\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"kiwi fruit\\\",\\\"num\\\":\\\"35\\\",\\\"price\\\":\\\"276.59\\\",\\\"type\\\":\\\"amet aliquip eiusmod\\\"}]\",\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://sandbox-acq.onerway.com/callback/testReceiveNotification\",\"screenHeight\":\"1200\",\"screenWidth\":\"375\",\"timeZoneOffset\":\"180\",\"transactionIp\":\"252.238.110.248\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36\"}",
    "txnType": "SALE"
}

标准令牌支付示例

当 checkResult 为 false 时，无需 CVV：

json

{
    "billingInformation": "{\"address\":\"889 Mill Close\",\"city\":\"Buckridgefield\",\"country\":\"US\",\"email\":\"Ryan.Purdy@gmail.com\",\"firstName\":\"Frederik\",\"identityNumber\":\"92066033023\",\"lastName\":\"Pfannerstill\",\"phone\":\"15209608948\",\"postalCode\":\"96542\",\"province\":\"CO\"}",
    "merchantCustId": "CustId-75S6-256P",
    "merchantNo": "800209",
    "merchantTxnId": "9e6aedb2-ecee-43b6-8c28-174e0e353c95",
    "merchantTxnTime": "2025-06-25 20:18:57",
    "orderAmount": "1",
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"address\":\"72981 Alejandrin Port\",\"city\":\"Lake Judd\",\"country\":\"US\",\"email\":\"Tracy_Stanton58@gmail.com\",\"firstName\":\"Noble\",\"identityNumber\":\"84880795738\",\"lastName\":\"Baumbach\",\"phone\":\"18434119887\",\"postalCode\":\"12053\",\"province\":\"CO\"}",
    "sign": "41c365542a39853dd0aa4504a3cea4d341db05dfe4d78cf264a827bb5dd07b79",
    "subProductType": "DIRECT",
    "tokenInfo": "{\"provider\":\"GooglePay\",\"tokenId\":\"{\\\"signature\\\":\\\"MEYCIQCvwmUnXStC/Qhdv6XQxe5xu3yiOCXYMpEp9tzdeHcQmgIhAOHakh9S47uHSPoObcSjHhIlQncEv+1oRkVY9zoYrYP7\\\",\\\"intermediateSigningKey\\\":{\\\"signedKey\\\":\\\"{\\\\\\\"keyValue\\\\\\\":\\\\\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE+F0IUGuqIge8NpRKXdhF+mHIu90N1X+uLJ0KuiYgqtMCNU/xQyn7FfeMUuIeLFFoFoRr/rvK/y3EtZUpTqjo5A\\\\\\\\u003d\\\\\\\\u003d\\\\\\\",\\\\\\\"keyExpiration\\\\\\\":\\\\\\\"1752655434646\\\\\\\"}\\\",\\\"signatures\\\":[\\\"MEQCID26+6e9vq0IHaWT3ORBCYJVR2Sr6eCpIO7V9fbKnXodAiBcu5gBmT/qwFjTsuRKmRPYYQfmhj4HV0auXrmHaPCPTw==\\\"]},\\\"protocolVersion\\\":\\\"ECv2\\\",\\\"signedMessage\\\":\\\"{\\\\\\\"encryptedMessage\\\\\\\":\\\\\\\"LFCsimI+8uLb6tX1mn0/c63DbvdPqOlLq8fJCJ8MnsTwvvQmaVWnLVFDikH5cePDCLz/D7Y8bUVW+Bfz38qB5WpcHtQrRoIQB1JEVoOL6tnFcrmQ87OeIfq9zgzWUp4TUF9NNJwYUit+2mrUeUR8elxq0ulavtiefhi7K0oIIFemBI2BfrlpIb/YjEsMbaAOLiYL+FvVyVxYiWeeGbsc5gAv0KJ9HrTKSIoMJ2fWoV/aMdX3iNnWTijr5x77JqHUdkMeo5xu/AUiODzqVAUl2UPCj/met2MFQpbvOea0102WdzrsviXisFniG5LQuxHyqXbYuoYRJhnpdk0F0XBL0tUAjiMd9rsULeCBc6JhxGgH+XnYorVVdXNKO08ZrFTQ+ZdaLEsiM+SatwGDa+Pt2+v5nbAq3SPwI0SgNmRdbkiOxdSKd//ZaooR0IQPQ21EJQAtdfr4KfMN0wmqA81VFrSuUySK8sVukyFde/OL9Fa/T0rLi7fqccF0d8Udl+C9Z3xReeMb03UuO+YcLT8g8QrdtDqungfCcP11hpmfx6M5/pebvZ1vYNFi\\\\\\\",\\\\\\\"ephemeralPublicKey\\\\\\\":\\\\\\\"BHcjhYHhu2QxoIGui2b451KY0ISiwi6u1y33bR0BHzqipB8XDx6YPAiRHYPI9umvwM+Pd9jGyNWBvOvI8xXiFaE\\\\\\\\u003d\\\\\\\",\\\\\\\"tag\\\\\\\":\\\\\\\"Ntfma/N099yxBNEd3lwB8aOjQws+K07IYa2Djfm5OeQ\\\\\\\\u003d\\\\\\\"}\\\"}\"}",
    "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"24\",\"contentLength\":\"65536\",\"javaEnabled\":false,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"butternut pumpkin\\\",\\\"num\\\":\\\"96\\\",\\\"price\\\":\\\"708.69\\\",\\\"type\\\":\\\"est\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"kiwi fruit\\\",\\\"num\\\":\\\"35\\\",\\\"price\\\":\\\"276.59\\\",\\\"type\\\":\\\"amet aliquip eiusmod\\\"}]\",\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://sandbox-acq.onerway.com/callback/testReceiveNotification\",\"screenHeight\":\"1200\",\"screenWidth\":\"375\",\"timeZoneOffset\":\"180\",\"transactionIp\":\"252.238.110.248\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36\"}",
    "txnType": "SALE"
}

常见错误场景

无效令牌格式

错误：令牌解析失败
原因：tokenInfoJson 参数包含格式错误或无效的 Google Pay 令牌数据
解决方案：验证 Google Pay 令牌格式正确并包含所有必需字段

令牌过期

错误：令牌验证失败
原因：Google Pay 令牌已过期且不再有效
解决方案：从客户请求新的 Google Pay 令牌并重试检查

无效签名

错误：请求签名验证失败
原因：sign 参数不正确或使用错误参数生成
解决方案：验证您的签名生成过程并确保包含所有参数

商户配置错误

错误：商户未配置 Google Pay
原因：您的商户账户未正确配置 Google Pay 处理
解决方案：联系 Onerway 支持以验证您的 Google Pay 商户配置

实施最佳实践

始终检查响应码：在使用 checkResult 之前验证 respCode 为 20000
处理两种场景：为 PAN_ONLY 和标准模式实现 UI 流程
安全收集 CVV：当 checkResult 为 true 时，使用适当的输入遮罩安全收集 CVV
错误处理：为 API 失败实现适当的错误处理
令牌重用：在检查和支付操作中使用相同的 Google Pay 令牌
超时管理：为检查 API 调用设置适当的超时时间

商户集成检查清单

接口集成：成功调用 PAN_ONLY 检查接口
响应解析：正确解析响应中的 checkResult
条件 UI：根据检查结果显示/隐藏 CVV 输入
CVV 收集：为 PAN_ONLY 模式实现安全的 CVV 输入
令牌支付：在需要时正确通过 cardInfo.cvv 传递 CVV
错误处理：优雅地处理所有错误场景
测试：测试 PAN_ONLY 和标准令牌场景
安全性：确保 CVV 得到安全处理且不被记录

收银台

下单

WebSDK

Android

绑卡支付

本地支付

Ethoca

RDR

Google Pay PAN_ONLY 检查

集成前置条件

接口请求参数

响应

data

集成流程

接口使用示例

令牌支付示例

PAN_ONLY 令牌支付示例

标准令牌支付示例

常见错误场景

无效令牌格式

令牌过期

无效签名

商户配置错误

实施最佳实践

商户集成检查清单

收银台

下单

WebSDK

Android

绑卡支付

本地支付

Google Pay PAN_ONLY 检查 ​

集成前置条件 ​

接口请求参数 ​

响应 ​

data ​

集成流程 ​

接口使用示例 ​

令牌支付示例 ​

PAN_ONLY 令牌支付示例 ​

标准令牌支付示例 ​

常见错误场景 ​

无效令牌格式 ​

令牌过期 ​

无效签名 ​

商户配置错误 ​

实施最佳实践 ​

商户集成检查清单 ​

Google Pay PAN_ONLY 检查

集成前置条件

接口请求参数

响应

data

集成流程

接口使用示例

令牌支付示例

PAN_ONLY 令牌支付示例

标准令牌支付示例

常见错误场景

无效令牌格式

令牌过期

无效签名

商户配置错误

实施最佳实践

商户集成检查清单