前提条件
请务必先完成以下步骤，然后再继续：
确定要启用智能触碰功能的账号
在继续操作之前，您需要确定哪个帐号将被指定为兑换发卡机构帐号。有两种方法可以确定这一点：
创建新的发卡机构帐号
新帐号的帐号联系信息中必须包含该商家的信息。有关如何在 Google Pay & Wallet Console 中执行此操作的说明，请参阅这篇支持文章。以下代码示例演示了如何使用 Google Wallet API 创建发卡机构帐号：
Java
/**
* Create a new Google Wallet Issuer account.
*
* @param issuerName The Issuer's name.
* @param issuerEmail The Issuer's email address.
* @throws IOException
*/
public void CreateIssuerAccount(String issuerName, String issuerEmail) throws IOException {
// New Issuer information
Issuer issuer =
new Issuer()
.setName(issuerName)
.setContactInfo(new IssuerContactInfo().setEmail(issuerEmail));
Issuer response = service.issuer().insert(issuer).execute();
System.out.println("Issuer insert response");
System.out.println(response.toPrettyString());
}
PHP
/**
* Create a new Google Wallet issuer account.
*
* @param string $issuerName The Issuer's name.
* @param string $issuerEmail The Issuer's email address.
*/
public function createIssuerAccount(string $issuerName, string $issuerEmail)
{
// New Issuer information
$issuer = new Google_Service_Walletobjects_Issuer([
'name' => $issuerName,
'contactInfo' => new Google_Service_Walletobjects_IssuerContactInfo([
'email' => $issuerEmail,
]),
]);
$response = $this->service->issuer->insert($issuer);
print "Issuer insert response\n";
print_r($response);
}
Python
def create_issuer_account(self, issuer_name: str, issuer_email: str):
"""Create a new Google Wallet Issuer account.
Args:
issuer_name (str): The Issuer's name.
issuer_email (str): The Issuer's email address.
"""
# New Issuer information
issuer = {'name': issuer_name, 'contactInfo': {'email': issuer_email}}
# Make the POST request
response = self.http_client.post(url=self.issuer_url, json=issuer)
print('Issuer insert response')
print(response.text)
C#
/// <summary>
/// Create a new Google Wallet Issuer account.
/// </summary>
/// <param name="issuerName">The Issuer's name.</param>
/// <param name="issuerEmail">The Issuer's email address.</param>
public void CreateIssuerAccount(string issuerName, string issuerEmail)
{
// New issuer information
Issuer issuer = new Issuer()
{
ContactInfo = new IssuerContactInfo()
{
Email = issuerEmail
},
Name = issuerName,
};
Stream responseStream = service.Issuer
.Insert(issuer)
.ExecuteAsStream();
StreamReader responseReader = new StreamReader(responseStream);
JObject jsonResponse = JObject.Parse(responseReader.ReadToEnd());
Console.WriteLine("Issuer insert response");
Console.WriteLine(jsonResponse.ToString());
}
Node.js
/**
* Create a new Google Wallet Issuer account.
*
* @param {string} issuerName The Issuer's name.
* @param {string} issuerEmail The Issuer's email address.
*/
async createIssuerAccount(issuerName, issuerEmail) {
// New Issuer information
let issuer = {
name: issuerName,
contactInfo: {
email: issuerEmail
}
};
let response = await this.httpClient.request({
url: this.issuerUrl,
method: 'POST',
data: issuer
});
console.log('Issuer insert response');
console.log(response);
}
最初，只有创建发卡机构帐号的主账号（服务帐号或用户）才能访问。您需要更新发卡机构帐号的权限，以包含应该能够管理卡券的任何其他用户或服务帐号。以下代码示例演示了如何更新发卡机构帐号权限。
Java
/**
* Update permissions for an existing Google Wallet Issuer account.
*
* <p><strong>Warning:</strong> This operation overwrites all existing permissions!
*
* <p>Example permissions list argument below. Copy the add entry as needed for each email address
* that will need access. Supported values for role are: 'READER', 'WRITER', and 'OWNER'
*
* <pre><code>
* ArrayList<Permission> permissions = new ArrayList<Permission>();
* permissions.add(new Permission().setEmailAddress("emailAddress").setRole("OWNER"));
* </code></pre>
*
* @param issuerId The Issuer ID being used for this request.
* @param permissions The list of email addresses and roles to assign.
* @throws IOException
*/
public void UpdateIssuerAccountPermissions(String issuerId, ArrayList<Permission> permissions)
throws IOException {
Permissions response =
service
.permissions()
.update(
Long.parseLong(issuerId),
new Permissions().setIssuerId(Long.parseLong(issuerId)).setPermissions(permissions))
.execute();
System.out.println("Issuer permissions update response");
System.out.println(response.toPrettyString());
}
PHP
/**
* Update permissions for an existing Google Wallet Issuer account.
*
* **Warning:** This operation overwrites all existing permissions!
*
* Example permissions list argument below. Copy the entry as
* needed for each email address that will need access. Supported
* values for role are: 'READER', 'WRITER', and 'OWNER'
*
* $permissions = array(
* new Google_Service_Walletobjects_Permission([
* 'emailAddress' => 'email-address',
* 'role' => 'OWNER',
* ]),
* );
*
* @param string $issuerId The Issuer ID being used for this request.
* @param array $permissions The list of email addresses and roles to assign.
*/
public function updateIssuerAccountPermissions(string $issuerId, array $permissions)
{
// Make the PUT request
$response = $this->service->permissions->update(
$issuerId,
new Google_Service_Walletobjects_Permissions([
'issuerId' => $issuerId,
'permissions' => $permissions,
])
);
print "Permissions update response\n";
print_r($response);
}
Python
def update_issuer_account_permissions(self, issuer_id: str,
permissions: List):
"""Update permissions for an existing Google Wallet Issuer account.
**Warning:** This operation overwrites all existing permissions!
Example permissions list argument below. Copy the dict entry as
needed for each email address that will need access. Supported
values for role are: 'READER', 'WRITER', and 'OWNER'
permissions = [
{
'emailAddress': 'email-address',
'role': 'OWNER'
}
]
Args:
issuer_id (str): The Issuer ID being used for this request.
permissions (List): The list of email addresses and roles to assign.
"""
response = self.http_client.put(url=f'{self.permissions_url}/{issuer_id}',
json={
'issuerId': issuer_id,
'permissions': permissions
})
print('Permissions update response')
print(response.text)
C#
/// <summary>
/// Update permissions for an existing Google Wallet Issuer account.
/// <para />
/// <strong>Warning:</strong> This operation overwrites all existing permissions!
/// <para />
/// Example permissions list argument below. Copy the add entry as needed for each email
/// address that will need access.Supported values for role are: 'READER', 'WRITER', and 'OWNER'
/// <para />
/// <![CDATA[List<Permission> permissions = new List<Permission>();]]>
/// <para />
/// permissions.Add(new Permission { EmailAddress = "emailAddress", Role = "OWNER"});
/// </summary>
/// <param name="issuerId">The issuer ID being used for this request.</param>
/// <param name="permissions">The list of email addresses and roles to assign.</param>
public void UpdateIssuerAccountPermissions(string issuerId, List<Permission> permissions)
{
Stream responseStream = service.Permissions
.Update(new Permissions
{
IssuerId = long.Parse(issuerId),
PermissionsValue = permissions
},
long.Parse(issuerId))
.ExecuteAsStream();
StreamReader responseReader = new StreamReader(responseStream);
JObject jsonResponse = JObject.Parse(responseReader.ReadToEnd());
Console.WriteLine("Issuer permissions update response");
Console.WriteLine(jsonResponse.ToString());
}
Node.js
/**
* Update permissions for an existing Google Wallet Issuer account.
*
* **Warning:** This operation overwrites all existing permissions!
*
* Example permissions list argument below. Copy the dict entry as
* needed for each email address that will need access. Supported
* values for role are: 'READER', 'WRITER', and 'OWNER'
*
* let permissions = [
* {
* 'emailAddress': 'email-address',
* 'role': 'OWNER',
* },
* ];
*
* @param {string} issuerId The Issuer ID being used for this request.
* @param {Array} permissions The list of email addresses and roles to assign.
*/
async updateIssuerPermissions(issuerId, permissions) {
let response = await this.httpClient.request({
url: `${this.permissionsUrl}/${issuerId}`,
method: 'PUT',
data: {
issuerId: issuerId,
permissions: permissions
}
});
console.log('Permissions update response');
console.log(response);
}
使用现有账号
您应根据以下条件确定是否可以使用包含现有卡券类的发卡机构帐号。
- 如果用于开发卡券的发行方帐号包含其他商家的类，您必须代表该商家设置一个新帐号。
- 如果用于开发卡券的发卡机构帐号仅包含该特定商家的类，则可以使用该帐号。
如果帐号符合这些条件，您必须使用商家的信息更新商家资料中的联系信息，以确保帐号名称可用于识别商家。只有您拥有此帐号的 API 访问权限。 其他卡券开发者应创建自己的发卡机构帐号。
兑换发卡机构账号配置
使用 Google Pay & Wallet Console
在兑换发卡机构帐号中，您需要执行以下步骤：
- 转到 Google Wallet API 部分
- 选择其他功能
- 选择添加身份验证密钥
- 上传公钥（
.pem文件）并指定密钥版本 - 选择创建身份验证密钥
成功上传身份验证密钥后，系统将为您提供收款方 ID。
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEchyXj869zfmKhRi9xP7f2AK07kEo
4lE7ZlWTN14jh4YBTny+hRGRXcUzevV9zSSPJlPHpqqu5pEwlv1xyFvE1w==
-----END PUBLIC KEY-----
使用 Google Wallet API
上传公钥
如需使用 Google Wallet API 分配公钥和密钥版本，您需要向颁发者端点发出 PATCH 请求。
PATCH https://walletobjects.googleapis.com/walletobjects/v1/issuer/{issuerId}
PATCH 请求正文类似于以下内容：
{
"smartTapMerchantData": {
"authenticationKeys": [
{
"id": 1,
"publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
},
{
"id": 2,
"publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
}
]
}
}
以下代码示例演示了如何更新发卡机构帐号，以包含之前提到的演示公钥：
Java
/**
* Add a new public key to an Issuer account.
*
* @param issuerId The issuer ID being used for this request.
* @throws IOException
*/
public void AddSmartTapKey(Long issuerId) throws IOException {
// New smart tap key information
Issuer patchBody =
new Issuer()
.setSmartTapMerchantData(
new SmartTapMerchantData()
.setAuthenticationKeys(
Arrays.asList(
new AuthenticationKey()
.setId(1)
.setPublicKeyPem(
"-----BEGIN PUBLIC KEY-----\n"
+ "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEchyXj869zfmKhRi9xP7f2AK07kEo\n"
+ "4lE7ZlWTN14jh4YBTny+hRGRXcUzevV9zSSPJlPHpqqu5pEwlv1xyFvE1w==\n"
+ "-----END PUBLIC KEY-----"))));
Issuer response = service.issuer().patch(issuerId, patchBody).execute();
System.out.println("Issuer patch response");
System.out.println(response.toPrettyString());
}
PHP
/**
* Add a new public key to an Issuer account.
*
* @param string $issuerId The issuer ID being used for this request.
*/
public function addSmartTapKey(string $issuerId)
{
// New smart tap key information
$patchBody = new Google_Service_Walletobjects_Issuer([
'smartTapMerchantData' => new Google_Service_Walletobjects_SmartTapMerchantData([
'authenticationKeys' => [
new Google_Service_Walletobjects_AuthenticationKey([
'id' => 1,
'publicKeyPem' => "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEchyXj869zfmKhRi9xP7f2AK07kEo\n4lE7ZlWTN14jh4YBTny+hRGRXcUzevV9zSSPJlPHpqqu5pEwlv1xyFvE1w==\n-----END PUBLIC KEY-----"
])
]
])
]);
$response = $this->service->issuer->patch($issuerId, $patchBody);
print "Issuer patch response\n";
print_r($response);
}
Python
def add_smart_tap_key(self, issuer_id: str) -> str:
"""Add a new public key to an Issuer account.
Args:
issuer_id (str): The issuer ID being used for this request.
"""
# New smart tap key information
patch_body = {
'smartTapMerchantData': {
'authenticationKeys': [{
'id':
1,
'publicKeyPem':
'-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEchyXj869zfmKhRi9xP7f2AK07kEo\n4lE7ZlWTN14jh4YBTny+hRGRXcUzevV9zSSPJlPHpqqu5pEwlv1xyFvE1w==\n-----END PUBLIC KEY-----'
}]
}
}
# Make the PATCH request
response = self.http_client.patch(url=f'{self.issuer_url}/{issuer_id}', json=patch_body)
print('Issuer patch response')
print(response.text)
return response.json()['smartTapMerchantData']['smartTapMerchantId']
C#
/// <summary>
/// Add a new public key to an Issuer account.
/// </summary>
/// <param name="issuerId">The issuer ID being used for this request.</param>
public void AddSmartTapKey(long issuerId)
{
// New smart tap key information
Issuer patchBody = new Issuer()
{
SmartTapMerchantData = new SmartTapMerchantData
{
AuthenticationKeys = new List<AuthenticationKey>
{
new AuthenticationKey
{
Id = 1,
PublicKeyPem = "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEchyXj869zfmKhRi9xP7f2AK07kEo\n4lE7ZlWTN14jh4YBTny+hRGRXcUzevV9zSSPJlPHpqqu5pEwlv1xyFvE1w==\n-----END PUBLIC KEY-----"
}
}
}
};
Stream responseStream = service.Issuer
.Patch(patchBody, issuerId)
.ExecuteAsStream();
StreamReader responseReader = new StreamReader(responseStream);
JObject jsonResponse = JObject.Parse(responseReader.ReadToEnd());
Console.WriteLine("Issuer patch response");
Console.WriteLine(jsonResponse.ToString());
}
Node.js
/**
* Add a new public key to an Issuer account.
*
* @param {string} issuerId The issuer ID being used for this request.
*/
async addSmartTapKey(issuerId) {
// New smart tap key information
let patchBody = {
smartTapMerchantData: {
authenticationKeys: [
{
id: 1,
publicKeyPem: '-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEchyXj869zfmKhRi9xP7f2AK07kEo\n4lE7ZlWTN14jh4YBTny+hRGRXcUzevV9zSSPJlPHpqqu5pEwlv1xyFvE1w==\n-----END PUBLIC KEY-----'
}
]
}
};
let response = await this.httpClient.request({
url: `${this.issuerUrl}/${issuerId}`,
method: 'PATCH',
data: patchBody
});
console.log('Issuer patch response');
console.log(response);
}
响应将包含您发送的正文和一个额外字段 smartTapMerchantData.smartTapMerchantId。这是兑换发卡机构帐号的收款方 ID。
获取收款方 ID
添加任何密钥和密钥版本后，您可以使用 Google Wallet API 向发卡机构端点发出 GET 请求，以获取收款方 ID。
GET https://walletobjects.googleapis.com/walletobjects/v1/issuer/{issuerId}
Java
/**
* Get the Collector ID for an Issuer account.
*
* @param issuerId The issuer ID being used for this request.
* @return The Collector ID
* @throws IOException
*/
public Long GetCollectorId(Long issuerId) throws IOException {
Issuer response = service.issuer().get(issuerId).execute();
System.out.println("Issuer patch response");
System.out.println(response.toPrettyString());
return response.getSmartTapMerchantData().getSmartTapMerchantId();
}
PHP
/**
* Get the Collector ID for an Issuer account.
*
* @param string $issuerId The issuer ID being used for this request.
* @return string The Collector ID.
*/
public function getCollectorId(string $issuerId)
{
$response = $this->service->issuer->get($issuerId);
print "Issuer get response\n";
print_r($response);
return $response['smartTapMerchantData']['smartTapMerchantId'];
}
Python
def get_collector_id(self, issuer_id: str) -> str:
"""Get the Collector ID for an Issuer account.
Args:
issuer_id (str): The issuer ID being used for this request.
"""
# Make the GET request
response = self.http_client.get(url=f'{self.issuer_url}/{issuer_id}')
print('Issuer get response')
print(response.text)
return response.json()['smartTapMerchantData']['smartTapMerchantId']
C#
/// <summary>
/// Get the Collector ID for an Issuer account.
/// </summary>
/// <param name="issuerId">The issuer ID being used for this request.</param>
/// <returns>The Collector ID</returns>
public string GetCollectorId(long issuerId)
{
Stream responseStream = service.Issuer
.Get(issuerId)
.ExecuteAsStream();
StreamReader responseReader = new StreamReader(responseStream);
JObject jsonResponse = JObject.Parse(responseReader.ReadToEnd());
Console.WriteLine("Issuer get response");
Console.WriteLine(jsonResponse.ToString());
return jsonResponse["smartTapMerchantData"]["smartTapMerchantId"].Value<string>();
}
Node.js
/**
* Get the Collector ID for an Issuer account.
*
* @param {string} issuerId The issuer ID being used for this request.
*
* @returns {string} The Collector ID
*/
async getCollectorId(issuerId) {
let response = await this.httpClient.request({
url: `${this.issuerUrl}/${issuerId}`,
method: 'GET'
});
console.log('Issuer patch response');
console.log(response);
return response.data.smartTapMerchantData.smartTapMerchantId;
}
响应将包含字段 smartTapMerchantData.smartTapMerchantId。这是兑换发卡机构帐号的收款方 ID。
发行方账号管理
卡券组织
您可以通过以下两种常用方法为多个商家管理卡券类和对象：
- 为所有商家提供统一的发卡机构帐号
- 为每个商家创建一个新的发卡机构帐号
例如，Foo-Loyalty 为两个商家分别管理会员回馈活动：ILuvCoffee 和 TeaLuv。您可以通过以下任一方式管理其卡券类：
| 做法 | 说明 |
|---|---|
| 单一发卡机构帐号 | 将所有会员卡类包含在一个发卡机构帐号“Foo-Loyalty”下。如果您计划跟踪类级别卡券可兑换的位置，则建议使用此选项。如果您从未授予您的商家该发卡机构帐号的 API 访问权限，也可以选择此选项。 |
| 单独的发卡机构帐号 | 创建两个单独的发卡机构帐号：“iLuvCoffee via Foo-Loyalty”和“teaLuv via Foo-Loyalty”。如果您想假定特定发卡机构帐号下的所有类别都可以在商家级别兑换，或者您计划向商家授予对该发卡机构帐号的 API 访问权限，则建议使用此选项。 |
兑换发卡机构账号
确定要使用的正确兑换发卡机构帐号时，需要考虑两种场景。
场景 1：商家已在使用智能触碰功能
如果商家确认他们已经可以通过终端从 Google 钱包兑换（商家已设置为兑换发卡机构），请按以下步骤操作：
- 申请商家的兑换发卡机构 ID
- 将商家的兑换发卡机构 ID 添加到卡券类的
redemptionIssuers属性中
场景 2：商家初次使用智能触碰
在这种情况下，商家具有支持智能触碰但尚未使用此功能的终端。商家、终端提供商或卡券开发者需要执行一次性设置，才能在商家终端上启用智能触碰功能。
如需了解详情，请参阅商家配置。