必要條件
在繼續操作之前，請務必完成下列步驟：
決定要啟用智慧感應功能的帳戶
繼續操作之前，您必須先找出要指定為兌換核發機構帳戶的帳戶。判斷結果的方法有兩種：
建立新的發卡機構帳戶
新帳戶的帳戶聯絡資訊必須包含該商家的資訊。如需在 Google Pay 和錢包主控台中執行這項操作的操作說明，請參閱這篇支援文章。下列程式碼範例示範如何使用 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 和錢包主控台
在兌換核發機構帳戶中，請按照下列步驟操作：
- 前往「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-----"
}
]
}
}
以下程式碼範例示範如何更新 Issuer 帳戶，以納入前述的示範公開金鑰：
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
新增任何金鑰和金鑰版本後，只要向核發者端點發出 GET 要求，即可使用 Google Wallet API 取得賣家 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 給該發卡機構帳戶，也很適合選擇這個方式。 |
| 不同的發卡機構帳戶 | 建立兩個獨立的發卡機構帳戶：「透過 Foo-Loyalty 兌換 iLuvCoffee」和「透過 Foo-Loyalty 兌換 TeaLuv」。如果您想假設特定核發者帳戶下的所有類別可在商家層級兌換，或是打算將核發者帳戶的存取權授予商家 API，建議您使用這個選項。 |
兌換核發機構帳戶
當您判斷要使用的正確兌換發卡機構帳戶時，會考量以下兩種情況。
情境 1：商家已在使用智慧感應功能
如果商家確認已能用終端機兌換 Google 錢包 (商家已設為兌換者)，請按照下列步驟操作：
- 要求商家兌換核發機構 ID
- 將商家的兌換核發機構 ID 新增至票證類別的
redemptionIssuers屬性
情境 2：商家第一次使用智慧感應功能
在這個情境中，商家有支援智慧感應功能的感應式刷卡機，但尚未啟用這項功能。商家、感應式刷卡機供應商或票證開發人員必須執行一次性設定，才能在商家的感應式刷卡機啟用智慧感應功能。
詳情請參閱「商家設定」。