Konfiguracja konta wydawcy

Wymagania wstępne

Zanim przejdziesz dalej, wykonaj te czynności:

• Wymagania wstępne

Wskaż konto, na którym chcesz używać smart tap

Zanim przejdziesz dalej, musisz określić, które konto zostanie oznaczone jako konto wystawcy elementów promocyjnych. Można to sprawdzić na dwa sposoby:

Utwórz nowe konto wydawcy

Informacje kontaktowe nowego konta muszą zawierać informacje o sprzedawcy. Instrukcje, jak to zrobić w Konsoli usług Google Pay i Portfela Google, znajdziesz w tym artykule pomocy. Poniższy przykładowy kod pokazuje, jak utworzyć konto wydawcy przy użyciu interfejsu 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);
}

Początkowo dostęp będzie mieć tylko podmiot zabezpieczeń (konto usługi lub użytkownik), który utworzył konto wystawcy. Musisz zaktualizować uprawnienia konta wystawcy, aby uwzględnić dodatkowych użytkowników lub konta usługi, które powinny zarządzać kartami. Poniższy przykładowy kod ilustruje aktualizację uprawnień konta wystawcy.

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&lt;Permission> permissions = new List&lt;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);
}

Użyj istniejącego konta

Poniższe kryteria pozwolą Ci określić, czy możesz użyć konta wystawcy zawierającego istniejące klasy kart.

• Jeśli konto wydawcy do tworzenia kart zawiera klasy innych sprzedawców, musisz utworzyć nowe konto w imieniu sprzedawcy.
• Jeśli Twoje konto wydawcy do tworzenia karty zawiera tylko klasy tego konkretnego sprzedawcy, można go użyć.

Jeśli konto spełnia te kryteria, musisz zaktualizować informacje kontaktowe w profilu firmy o dane sprzedawcy, aby nazwa konta odpowiadała sprzedawcy. Tylko Ty musisz mieć dostęp do tego konta na poziomie interfejsu API. Dodatkowi deweloperzy kart powinni utworzyć własne konta wystawcy.

Konfiguracja konta wydawcy elementów promocyjnych

Korzystanie z Konsoli usług Google Pay i Portfela Google

Na koncie wydawcy elementów promocyjnych wykonaj te czynności:

1. Przejdź do sekcji Google Wallet API
2. Wybierz Dodatkowe funkcje.
3. Wybierz Dodaj klucz uwierzytelniania.
4. Prześlij klucz publiczny (plik .pem) i określ wersję klucza
5. Wybierz Utwórz klucz uwierzytelniania.

Identyfikator sprzedawcy zostanie Ci przekazany po przesłaniu klucza uwierzytelniania.

Uwaga: jeśli dostawca terminala nie udostępni Ci klucza publicznego, dopóki nie podasz identyfikatora sprzedawcy, możesz go wygenerować za pomocą poniższego klucza demonstracyjnego. Pamiętaj, aby usunąć ten klucz demonstracyjny, gdy otrzymasz właściwy klucz publiczny od dostawcy terminala.

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEchyXj869zfmKhRi9xP7f2AK07kEo
4lE7ZlWTN14jh4YBTny+hRGRXcUzevV9zSSPJlPHpqqu5pEwlv1xyFvE1w==
-----END PUBLIC KEY-----

Użyj Google Wallet API

Prześlij klucz publiczny

Aby przypisać klucze publiczne i wersje kluczy przy użyciu interfejsu Google Wallet API, musisz wysłać żądanie PATCH do punktu końcowego Issuers.

PATCH https://walletobjects.googleapis.com/walletobjects/v1/issuer/{issuerId}

Ważne: właściwość smartTapMerchantData.authenticationKeys[].id musi być liczbą całkowitą z zakresu od 1 do 2,147,483,647 (włącznie). Każdy klucz publiczny musi mieć unikalną wersję klucza.

Treść żądania PATCH będzie wyglądać mniej więcej tak:

{
    "smartTapMerchantData": {
        "authenticationKeys": [
            {
                "id": 1,
                "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
            },
            {
                "id": 2,
                "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
            }
        ]
    }
}

Poniższy przykładowy kod pokazuje, jak zaktualizować konto wydawcy, dodając wspomniany wcześniej klucz publiczny w wersji demonstracyjnej:

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);
}

Odpowiedź będzie zawierać wysłaną treść i dodatkowe pole smartTapMerchantData.smartTapMerchantId. Jest to identyfikator sprzedawcy konta wydawcy elementów promocyjnych.

Uzyskiwanie identyfikatora sprzedawcy

Po dodaniu kluczy i wersji kluczy możesz użyć interfejsu Google Wallet API, aby uzyskać identyfikator sprzedawcy, wysyłając żądanie GET do punktu końcowego wystawcy.

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;
}

Odpowiedź będzie zawierać pole smartTapMerchantData.smartTapMerchantId. Jest to identyfikator sprzedawcy konta wydawcy elementów promocyjnych.

Zarządzanie kontem wydawcy

Organizacja karty

Istnieją 2 typowe metody zarządzania klasami i obiektami kart wielu sprzedawców:

• Jedno centralne konto wystawcy dla wszystkich sprzedawców
• Jedno nowe konto wydawcy dla każdego sprzedawcy

Na przykład Foo-Loyalty zarządza oddzielnymi programami lojalnościowymi dla 2 sprzedawców: IluvCoffee i TeaLuv. Zajęcia z karnetów można zarządzać na jeden z tych sposobów:

Podejście	Opis
Konto pojedynczego wydawcy	wszystkie klasy programu lojalnościowego na jednym koncie wystawcy „Foo-Loyalty”. Ta opcja jest zalecana, jeśli zamierzasz śledzić miejsca wykorzystania kart na poziomie klasy. Jest to też dobre rozwiązanie, jeśli nigdy nie przyznajesz sprzedawcom dostępu do tego konta wydawcy.
Oddzielne konta wydawców	Utwórz 2 osobne konta wystawcy: „iLuvCoffee przez Foo-Loyalty” i „teaLuv przez Foo-Loyalty”. Ta opcja jest zalecana, jeśli chcesz założyć, że wszystkie klasy na określonym koncie wydawcy są dostępne na poziomie sprzedawcy lub jeśli planujesz przyznać sprzedawcom dostęp do konta wydawcy przez interfejs API.

Konto wydawcy wykorzystania

Wybierając odpowiednie konto wydawcy elementów promocyjnych, należy wziąć pod uwagę 2 scenariusze.

Scenariusz 1. Sprzedawca korzysta już z smart tap

Jeśli sprzedawca potwierdzi, że może już wykorzystać kod z Portfela Google za pomocą terminali (sprzedawca jest już skonfigurowany jako wydawca elementów promocyjnych), wykonaj te czynności:

1. Prośba o identyfikator wydawcy elementów promocyjnych
2. Dodaj identyfikator wydawcy elementów promocyjnych do właściwości redemptionIssuers klasy karty

Scenariusz 2. Sprzedawca dopiero zaczyna korzystać z smart tap

W tym przypadku sprzedawca ma terminale obsługujące smart tap, ale nie korzysta z tej funkcji. Sprzedawca, dostawca terminala lub deweloper karty będzie musiał przeprowadzić jednorazową konfigurację, aby włączyć smart tap w terminalach sprzedawcy.

Więcej informacji znajdziesz w artykule o konfiguracji sprzedawcy.