Google Pay™

准备工作

Google Pay™ 网页集成指南

如果您打算通过 Google Pay™ 进行集成，必须在连接本接口之前完成 Google Pay 要求的准备工作。详细要求请参阅 Google Pay 集成文档。

如果您向客户提供 Google Pay 作为支付方式，必须按照 Google Pay 网页品牌指南 使用官方的 Google Pay 标志和按钮素材，不得修改 Google Pay 素材的颜色、比例或外观。

您需要基于 Google Pay 网页开发者文档、Google Pay 网页集成检查清单 和 Google Pay 网页品牌指南 将网页应用与 Google Pay API 集成，获取相应的支付令牌，并提交到我们的接口。

集成 Google Pay 时，您需要遵守 Google Pay 和钱包 API 可接受使用政策 并接受 Google Pay API 服务条款 中定义的条款。

我们在 Google Pay API 中支持 VISA、Mastercard、American Express 和 JCB 卡组织。您可以在 allowedCardNetworks 属性中定义这些值，并在 Google Pay 网页开发者文档 中找到适当的值。

Google Pay 需要账单地址，请确保包含必要的参数。更多详情，请参阅 BillingAddressParameters。

账单地址请求示例：

json

"allowedPaymentMethods": [
 {
 "type": "CARD",
 "parameters": {
 "billingAddressRequired": true,
 "billingAddressParameters": {
 "phoneNumberRequired": true,
 "format": "MIN"
 },
 "allowedCardNetworks": ["VISA","MASTERCARD","AMEX","JCB"],
 "allowedAuthMethods": ["PAN_ONLY","CRYPTOGRAM_3DS"]
 },
 "tokenizationSpecification": {...}
 }
]

满足集成条件后，请在 Google 商家控制台上完成注册。

准备 gateway 和 gatewayMerchantId

我们为 Google Pay 提供网关集成支持；我们代表您处理解密。

当您作为商家与 Google Pay API 集成时，请确保在 TokenizationSpecification 对象中设置以下值：

gateway: fireantpay
gatewayMerchantId : 在商户平台中，商户 > 商户信息 部分，您可以找到 gatewayMerchantId。

在 TokenizationSpecification 中设置。

json

"tokenizationSpecification": {
 "type": "PAYMENT_GATEWAY",
 "parameters": {
 "gateway": "fireantpay",
 "gatewayMerchantId": "<YOUR_GATEWAY_MERCHANT_ID>"
 }
}

Google Pay™ 交易的 3DS 要求

Google Pay 提供两种不同的 授权方式：PAN_ONLY 和 CRYPTOGRAM_3DS。

我们与 Google Pay 的集成支持两种类型的卡凭证：

PAN_ONLY：存储在 Google Pay™ 中的实体卡详情。
需要 3DS：是，适用标准 3DS 流程。
支持国家/地区：欧洲、美国和加拿大。
CRYPTOGRAM_3DS：存储在设备上的令牌化虚拟卡。
需要 3DS：否，由 Google Pay™ 执行认证。
支持国家/地区：仅限美国。

对于 PAN_ONLY 交易，如果交易受 PSD2 约束（例如在欧洲经济区/英国），则需要 3DS 认证。当需要 3DS 认证时，接口响应中的 redirectUrl 字段将返回 3DS 认证 URL。商户需要将用户的浏览器重定向到此 URL，引导他们完成 3DS 认证流程。认证完成后，交易结果将通过 notifyUrl 通知商户，并通过 returnUrl 重定向回商户网店。

支付请求

支付接口请求

按照示例格式填写相关信息。
使用下表中的确切字段名提交字段；参数名区分大小写。
发送到本系统网关的所有命令使用 POST 方法和 UTF-8 编码。
在组合、加密和提交支付参数之前，去除每个参数值的首尾空格。

支付流程

Google Pay

本接口使用服务器到服务器集成（不是浏览器表单提交）。在整个支付过程中，浏览器 URL 保持不变。

sequenceDiagram
 participant User as 消费者
 participant Merchant as 商户系统
 participant GPay as Google Pay JS API
 participant GServer as Google Pay 服务器
 participant PSP as 支付服务提供商/收单机构
 participant Bank as 发卡行/卡组织

 Note over User,Merchant: 1. 准备：页面加载和可用性检查
 Merchant->>Merchant: 加载 Google Pay JS 库<br>(pay.js)
 Merchant->>GPay: isReadyToPay() 检查
 Note over GPay: 检查设备/浏览器<br>是否支持 Google Pay
 GPay-->>Merchant: 返回可用性结果
 alt Google Pay 可用
 Merchant->>Merchant: 显示 Google Pay 按钮
 else 不可用
 Merchant->>Merchant: 隐藏或回退到其他支付方式
 end

 Note over User,Merchant: 2. 用户发起支付
 User->>Merchant: 点击 Google Pay 按钮
 Merchant->>GPay: loadPaymentData()
 Note over Merchant,GPay: 传递支付请求参数<br>transactionInfo、merchantInfo 等

 Note over User,GServer: 3. Google 支付表单交互
 GPay->>User: 显示 Google 支付表单
 User->>GPay: 选择已保存的卡/添加新卡
 GPay->>GServer: 请求支付数据
 GServer->>GServer: 生成支付令牌<br>和动态密码
 GServer-->>GPay: 返回加密支付数据
 GPay-->>Merchant: 返回加密支付数据<br>(paymentMethodData)

 Note over Merchant,Bank: 4. 支付处理和授权
 Merchant->>PSP: 提交授权请求<br>(包含加密 paymentMethodData)
 Note over PSP: 解密支付数据<br>提取支付令牌和密码

 PSP->>Bank: 转发授权请求<br>(包含支付令牌)
 Bank-->>PSP: 返回授权结果

 alt 需要 3D 安全认证
 PSP-->>Merchant: 返回 redirectUrl<br>(3DS 验证 URL)
 Merchant->>User: 重定向到 3DS 验证页面
 User->>Bank: 完成 3DS 验证<br>(短信/指纹/密码)
 Bank-->>User: 验证完成
 User-->>Merchant: 重定向回商户页面
 Merchant->>PSP: 确认 3DS 验证结果
 PSP-->>Merchant: 返回最终授权结果
 else 无需 3DS 验证
 PSP-->>Merchant: 直接返回授权结果
 end

 Note over User,Merchant: 5. 结果显示和清理
 alt 支付成功
 Merchant->>User: 显示支付成功页面
 else 支付失败
 Merchant->>User: 显示支付失败信息
 end

1.付款人在商户店铺（如 SHOPLINE）选择商品并进入支付流程。

2.商户客户端检查设备/浏览器是否支持 Google Pay。如果支持，则启动 Google Pay；如果不支持，则回退到其他支付方式。

3.付款人点击 Google Pay 按钮并从列表中选择信用卡进行支付。Google Pay 服务器生成加密支付数据包并返回给商户客户端。然后商户将加密数据提交给 Fireantpay 完成流程。

4.商户客户端将支付数据和订单信息提交给 Fireantpay（支付服务提供商）。后端组装请求并提交到本接口。

5.如果 PAN_ONLY 模式触发 3D 安全认证，您需要重定向到 redirectUrl 完成验证。如果使用 CRYPTOGRAM_3DS 模式，则不需要 3D 安全认证。

6.交易成功后，Fireantpay 异步通知商户交易结果。

7.如果商户未收到 Fireantpay 的交易回调且订单状态未知，商户必须调用 Fireantpay 的单笔订单查询接口检查交易结果。

表单参数格式说明

参数名	类型	长度	必填	说明
订单信息
merNo	字符串	5	是	商户号；支付平台分配的唯一 ID
gatewayNo	字符串	8	是	网关接入号；商户接入的唯一 ID
orderNo	字符串	50	是	店铺订单号；唯一，同一店铺系统中不重复
orderCurrency	字符串	3	是	支付币种（3 位 ISO 4217 代码；见附录）
orderAmount	字符串	10	是	订单总金额；2 位小数，需要时四舍五入
shipFee	字符串	100	否	运费；数字，最多 2 位小数
discount	字符串	100	否	折扣；默认为负数，数字，最多 2 位小数
goodsInfo	字符串	5000	是	商品详细信息；见附录：商品信息
信用卡信息
tradeType	字符串	50	是	交易类型；固定值：`GOOGLEPAY`（钱包支付必需）
cardToken	字符串	500	是	Google Pay JS 生成的支付数据。支付数据示例
用户信息
firstName	字符串	100	是	名字
lastName	字符串	50	是	姓氏
email	字符串	200	是	用户邮箱
ip	字符串	100	是	用户 IP 地址
phone	字符串	50	是	用户电话
country	字符串	100	是	用户国家（ISO 3166-1 2 位代码，如 `US`）
state	字符串	100	否	用户州/省
city	字符串	100	是	用户城市
address	字符串	500	是	用户详细地址
zip	字符串	100	是	用户邮编
收货人信息
shipFirstName	字符串	100	否	收货人名字
shipLastName	字符串	100	否	收货人姓氏
shipEmail	字符串	100	否	收货人邮箱
shipPhone	字符串	100	否	收货人电话
shipCountry	字符串	100	否	收货人国家（ISO 3166-1 2 位代码）
shipState	字符串	100	否	收货人州/省
shipCity	字符串	100	否	收货人城市
shipAddress	字符串	100	否	收货人详细地址
shipZip	字符串	100	否	收货人邮编
设备/操作系统信息
os	字符串	50	是	持卡人操作系统
brower	字符串	50	是	浏览器类型
browerLang	字符串	50	是	浏览器语言
timeZone	字符串	50	是	时区
resolution	字符串	50	是	屏幕分辨率
其他信息
webSite	字符串	200	是	来源网站域名
notifyUrl	字符串	200	是	异步通知 URL；平台 POST 结果到此地址；回复 `OK`。异步通知示例
returnUrl	字符串	200	是	实时返回 URL；用于 3D 安全重定向
signInfo	字符串	32	是	SHA256 签名；固定顺序：`merNo+gatewayNo+orderNo+orderCurrency+orderAmount+tradeType+cardToken+merKey`；无空格或 `+`。详情见附录：SHA256 签名方法。
remark	字符串	500	否	商户自定义备注（原样返回）

支付接口响应

接口说明

接收并处理商户订单后，网关以 UTF-8 编码的 XML 格式实时返回支付结果。

返回数据说明

先解析 XML 响应，然后判断支付结果。见以下示例。

表单参数格式说明

参数名	类型	最大长度	说明
merNo	字符串	5	商户号
gatewayNo	字符串	8	网关接入号
tradeNo	字符串	50	平台交易流水号（唯一）
orderNo	字符串	50	商户订单号
orderCurrency	字符串	3	订单币种（ISO 4217）
orderAmount	字符串	10	订单金额
orderStatus	字符串	1	交易状态：-1=待处理 0=失败 1=成功 5=失败（3D 放弃）
orderInfo	字符串	100	交易结果信息
billAddress	字符串	100	账单描述符（仅成功时返回）
returnType	字符串	1	返回类型：1（浏览器实时）2（服务器实时）3（服务器异步）
orderErrorCode	字符串	50	错误代码；`00` = 成功
signInfo	字符串	32	SHA256 签名：`merNo+gatewayNo+tradeNo+orderNo+orderCurrency+orderAmount+orderStatus+orderInfo+merKey`
remark	字符串	500	商户备注（原样返回）
redirectUrl	字符串	500	3D 安全重定向 URL

支付返回示例

当使用 PAN_ONLY 类型且需要 3DS 认证时，响应示例如下：

xml

<?xml version="1.0" encoding="UTF-8"?>
<respon>
<merNo>80000</merNo>
<gatewayNo>80000001</gatewayNo>
<tradeNo>N025050101235959566838</tradeNo>
<orderNo>Test-123456</orderNo>
<orderAmount>10.00</orderAmount>
<orderCurrency>USD</orderCurrency>
<orderStatus>-1</orderStatus>
<orderErrorCode></orderErrorCode>
<orderInfo></orderInfo>
<returnType>2</returnType>
<billAddress>Test Descriptor</billAddress>
<signInfo>B359F45698D1CE8A341C64815D346C9EDA8F14657D997901EA4D30FFODFC232A</signInfo>
<remark></remark>
<redirectUrl>http://sandbox.fireantpay.com/ccpg/threeDSProcessingPage?threeDSToken=92095B5D2549DC544625F8B432D47A63</redirectUrl>
</respon>

当不需要 3DS 认证时，响应示例如下：

xml

<?xml version="1.0" encoding="UTF-8"?>
<respon>
<merNo>80000</merNo>
<gatewayNo>80000001</gatewayNo>
<tradeNo>N025050101235959566838</tradeNo>
<orderNo>Test-123456</orderNo>
<orderAmount>10.00</orderAmount>
<orderCurrency>USD</orderCurrency>
<orderStatus>1</orderStatus>
<orderErrorCode>00</orderErrorCode>
<orderInfo>Approved</orderInfo>
<returnType>2</returnType>
<billAddress>Test Descriptor</billAddress>
<signInfo>B359F45698D1CE8A341C64815D346C9EDA8F14657D997901EA4D30FFODFC232A</signInfo>
<remark></remark>
<redirectUrl></redirectUrl>
</respon>

异步通知示例

clojure

Content-Type: application/x-www-form-urlencoded

merNo=80000&gatewayNo=80000001&tradeNo=N025050101235959566838&orderNo=Test-123456&orderAmount=10.00&orderCurrency=USD&orderStatus=1&orderErrorCode=00&orderInfo=Approved&returnType=2&billAddress=Test%20Descriptor&signInfo=B359F45698D1CE8A341C64815D346C9EDA8F14657D997901EA4D30FFODFC232A&remark=&redirectUrl=

常见错误

I0013：签名值（signInfo）错误

检查 merKey 的正确性和大小写一致性。
使用 SHA256 签名。
去除组合参数的所有首尾空格。

I0014：测试网关接入号 → 生产支付网关

开发期间使用测试网关。
测试完成后联系客服将商户号切换到生产环境。

I0015：生产网关接入号 → 测试支付网关

切换到生产环境后，将代码中的提交 URL 更新为生产端点。

E0008：重复支付

短时间内（约 30 秒）多次提交同一订单将被阻止，以防止重复支付。

附录

商品信息

格式（固定顺序）：

商品名称#,#商品ID#,#单价#,#数量#;#下一个商品...

字段之间用 #,# 分隔
商品之间用 #;# 分隔
空值用 0 表示
币种与订单币种一致
所有符号为半角

示例：

商品1#,#ID1#,#10.00#,#2#;#商品2#,#ID2#,#15.50#,#1

交易币种 ISO 4217

代码	英文说明	中文说明
CNY	Chinese Yuan	人民币
USD	US Dollar	美元
HKD	Hong Kong Dollar	港币
GBP	Pound Sterling	英镑
JPY	Japanese Yen	日元
EUR	Euro	欧元
AUD	Australian Dollar	澳元
SGD	Singapore Dollar	新加坡元
NZD	New Zealand Dollar	新西兰元
TWD	New Taiwan Dollar	台币
KRW	South Korean Won	韩元
DKK	Danish Krone	丹麦克朗
MYR	Malaysian Ringgit	马币
THB	Thai Baht	泰铢
INR	Indian Rupee	印度卢比
PHP	Philippine Peso	菲律宾比索
CHF	Swiss Franc	瑞士法郎
SEK	Swedish Krona	瑞典克朗
ILS	Israeli New Shekel	新谢克尔
ZAR	South African Rand	兰特
RUB	Russian Ruble	卢布
NOK	Norwegian Krone	挪威克朗
AED	UAE Dirham	迪拉姆
ARS	Argentine Peso	阿根廷比索
BRL	Brazilian Real	巴西雷亚尔
MMK	Myanmar Kyat	缅币
CAD	Canadian Dollar	加元
COP	Colombian Peso	哥伦比亚比索
HUF	Hungarian Forint	匈牙利福林
IDR	Indonesian Rupiah	印尼卢比
KWD	Kuwaiti Dinar	科威特第纳尔
LAK	Laotian Kip	老挝基普
MXN	Mexican Peso	墨西哥比索
NGN	Nigerian Naira	尼日利亚奈拉
PLN	Polish Złoty	波兰兹罗提
QAR	Qatari Riyal	卡塔尔里亚尔
SAR	Saudi Riyal	沙特里亚尔
TRY	Turkish Lira	新土耳其里拉
VND	Vietnamese Dong	越南盾

错误列表

代码	说明
I0001	商户号不能为空
I0002	网关号不能为空
I0003	加密值不能为空
I0004	商户号和网关号不匹配
I0005	商户号未激活
I0006	商户号已禁用
I0007	商户号不存在
I0008	商户状态异常
I0009	网关接入号未激活
I0010	网关接入号已禁用
I0011	网关接入号已删除
I0012	网关状态异常
I0013	signInfo 无效
I0014	测试网关 → 生产接口
I0015	生产网关 → 测试接口
I0016	网关未绑定到此接口
I0017	订单号不能为空
I0018	订单号超过 50 个字符
I0019	订单金额不能为空
I0020	订单金额无效
I0021	金额必须有 ≤2 位小数且 ≥0
I0022	币种不能为空
I0023	币种无效
I0024	返回 URL 不能为空
I0025	返回 URL 超过 1000 个字符
I0059	缺少必需参数
I0060	参数长度无效
I0061	此订单在 24 小时内已有成功交易
I0062	系统异常
I0067	备注超过 500 个字符
I0068	双方验证失败
I0069	请选择支付方式
I0070	请选择支付类型
I0071	IP 不能为空
I0072	IP 格式无效
I0092	支付方式无效
I0115	订单未找到
I0132	交易类型不能为空
I0133	交易类型无效
I0134	Appid 不能为空
I0135	Openid 不能为空
I0136	商品信息不能为空
R0000	高风险
R0001	网站未提交/未审批
R0002	跨境交易
C0001	网关未绑定到渠道
C0002	费率未设置
E0001	操作超时
E0008	重复支付
T0001	测试支付成功
U0001	持卡人取消

SHA256 签名方法

Java

java

signInfo=sha256(merNo+gateWayNo+orderNo+orderCurrency+orderAmount+tradeType+cardToken+merKey);

PHP

php

$signInfo=hash("sha256",$merNo.$gateWayNo.$orderNo.$orderCurrency.$orderAmount.$tradeType.$cardToken.$merKey);

Google Pay 支付数据

您需要参考 Google 的教程获取支付数据。支付数据包含我们需要的支付令牌和其他数据。您需要将整个支付数据传递给我们。

//参考 Google 教程的第 9 步，您可以通过 paymentsClient 获取支付数据。
paymentsClient.loadPaymentData(paymentDataRequest).then(function(paymentData){
 // 请将整个支付数据作为我们接口中的 cardToken 参数传递给我们。
 const cardToken = JSON.stringify(paymentData);
}).catch(function(err){
 // 在开发者控制台中显示错误以便调试
 console.error(err);
});

Google Pay 支付数据示例

json

{
 "apiVersion": 2,
 "apiVersionMinor": 0,
 "paymentMethodData": {
 "description": "Test Card: Visa •••• 1111",
 "info": {
 "assuranceDetails": {
 "accountVerified": true,
 "cardHolderAuthenticated": false
 },
 "cardDetails": "1111",
 "cardFundingSource": "CREDIT",
 "cardNetwork": "VISA"
 },
 "tokenizationData": {
 "token": "{\"signature\":\"MEYCIQDevxpK7wCKIeKWSctph5XaFHIliZny8XLaCbJjYTPe/QIhANTTPQXZhbXqdeDAGdm+TVzmeSNIpGg8584x28AlCvCR\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHeJFV5RiBvt2N2wNy6A\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1775121013140\\\"}\",\"signatures\":[\"MEQCICGh1LYitMMNCb+2i+iIP8QR/0lCbwaIeorsHOQtLCGLAiBeKWML5diXND6eWSyREpsWr/g7shRhJKe2aovJqPO2zg\\u003d\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"gv+gp98+2UtJbC8UCXtGni8Tu7Y\"}\"}",
 "type": "PAYMENT_GATEWAY"
 },
 "type": "CARD"
 }

支付提交示例 PHP

php

$data = array(
 'merNo' => $merNo,
 'gatewayNo' => $gatewayNo,
 'orderNo' => $orderNo,
 'orderAmount' => $orderAmount,
 'orderCurrency' => $orderCurrency,
 'shipFee' => $shipFee,
 'firstName' => $firstName,
 'lastName' => $lastName,
 'email' => $email,
 'phone' => $phone,
 'zip' => $zip,
 'address' => $address,
 'city' => $city,
 'state' => $state,
 'country' => $country,
 'shipFirstName' => $shipFirstName,
 'shipLastName' => $shipLastName,
 'shipPhone' => $shipPhone,
 'shipEmail' => $shipEmail,
 'shipCountry' => $shipCountry,
 'shipState' => $shipState,
 'shipCity' => $shipCity,
 'shipAddress' => $shipAddress,
 'shipZip' => $shipZip,
 'returnUrl' => $returnUrl,
 'notifyUrl' => $notifyUrl,
 'shipMethod' => $shipMethod,
 'signInfo' => $signInfo,
 'cardToken' => $cardToken,
 'tradeType' => $tradeType,
 'ip' => $ip,
 'os' => $os,
 'brower' => $brower,
 'browerLang' => $browerLang,
 'timeZone' => $timeZone,
 'resolution' => $resolution,
 'goodsInfo' => $goodsInfo
);

// 通过 CURL 提交到 FireAnt 支付网关
$result = curl_post('https://sandbox.fireantpay.com/TPInterface', http_build_query($data));
$xmlstring = simplexml_load_string($result, 'SimpleXMLElement', LIBXML_NOCDATA);
$value_array = json_decode(json_encode($xmlstring), true);

// 如果令牌类型为 PAN_ONLY，用户需要完成 3DS 认证。
// redirectUrl 字段将提供 3DS 认证 URL。
// 您需要在浏览器中重定向到此 URL，让用户完成 3DS 认证。
if (!empty($value_array['redirectUrl'])) {
 header('Location:'.$value_array['redirectUrl']);
 exit;
}

// 获取订单状态
$orderStatus = $value_array['orderStatus'];
if ($orderStatus == "1") {
 echo "支付成功";
}

Google Pay™ ​

准备工作 ​

Google Pay™ 网页集成指南 ​

准备 gateway 和 gatewayMerchantId ​

Google Pay™ 交易的 3DS 要求 ​

支付请求 ​

支付接口请求 ​

支付流程 ​

Google Pay ​

表单参数格式说明 ​

​

支付接口响应 ​

接口说明 ​

返回数据说明 ​

表单参数格式说明 ​

支付返回示例 ​

异步通知示例 ​

常见错误 ​

I0013：签名值（signInfo）错误 ​

I0014：测试网关接入号 → 生产支付网关 ​

I0015：生产网关接入号 → 测试支付网关 ​

E0008：重复支付 ​

附录 ​

商品信息 ​

交易币种 ISO 4217 ​

错误列表 ​

SHA256 签名方法 ​

Java ​

PHP ​

Google Pay 支付数据 ​

支付提交示例 PHP ​

Google Pay™

准备工作

Google Pay™ 网页集成指南

准备 gateway 和 gatewayMerchantId

Google Pay™ 交易的 3DS 要求

支付请求

支付接口请求

支付流程

Google Pay

表单参数格式说明

支付接口响应

接口说明

返回数据说明

表单参数格式说明

支付返回示例

异步通知示例

常见错误

I0013：签名值（signInfo）错误

I0014：测试网关接入号 → 生产支付网关

I0015：生产网关接入号 → 测试支付网关

E0008：重复支付

附录

商品信息

交易币种 ISO 4217

错误列表

SHA256 签名方法

Java

PHP

Google Pay 支付数据

支付提交示例 PHP