Neste documento, listamos a terminologia e os conceitos comuns que você precisa conhecer para usar a API Google Wallet.
Passes
Aprovado
Um cartão é uma instância de um objeto de cartão emitido para que o usuário salve na Carteira do Google. A API Google Wallet oferece suporte a vários tipos comuns de cartão, incluindo cartões de embarque, ingressos de eventos, carteiras de identidade e muito mais. A API Google Wallet também oferece um tipo de cartão genérico que pode ser usado para criar cartões sem suporte específico.
Na maioria dos casos, um cartão é criado usando uma classe de cartões e um objeto de cartões.
Emissor de cartão
Um emissor de cartão é uma entidade que cria cartões e os emite para que os usuários salvem na Carteira do Google. O emissor é o proprietário dos cartões e pode criar, emitir e atualizar. Os emissores de cartão podem ser desenvolvedores individuais, empresas e organizações, bem como agregadores que criam e emitem cartões em nome de terceiros, como uma empresa especializada na implementação de ingressos para eventos ou cupons para varejistas.
Classe de cartões
Uma classe de cartões pode ser considerada um modelo compartilhado que serve de base para a criação de cartões. Uma classe de cartões define certas propriedades que serão incluídas em todos os cartões que a utilizam. Um emissor de cartão pode criar várias classes, cada uma com o próprio conjunto distinto de propriedades que definem atributos como estilo e aparência, além de recursos adicionais, como Toque inteligente e inscrição e login.
Na maioria dos casos, um cartão é criado fornecendo uma classe de cartões para definir o modelo e um objeto de cartões para definir as especificidades do cartão individual que está sendo emitido.
Objeto de cartões
Um objeto de cartão define um cartão individual emitido para um usuário salvar na Carteira do Google. Objetos de cartões geralmente contêm informações específicas do usuário. Por exemplo, embora uma classe de cartões possa definir como será um cartão de vale-presente de uma loja específica, o objeto de cartões fornecerá detalhes específicos, como o saldo ou a data de validade.
Um objeto de cartões precisa ser criado para cada cartão emitido, ao contrário das classes de cartões, que podem ser compartilhadas entre muitas instâncias de cartão.
Cartões pessoais
Alguns cartões criados com a API Google Wallet podem conter dados confidenciais do usuário. Eles exigem proteção extra para manter os dados dos usuários seguros e são gerenciados de forma diferente na API Google Wallet com o uso do tipo Cartão pessoal genérico. O cartão pessoal genérico deve ser usado nos casos em que dados sensíveis (conforme definido na Política de Uso aceitável da API Google Wallet) são incluídos no cartão e podem estar sujeitos a controles de privacidade e análises adicionais durante a integração.
Toque inteligente
O Toque inteligente é um protocolo de comunicação a curta distância do Google para transmitir dados entre um dispositivo móvel e um terminal NFC. Com a tecnologia de Toque inteligente, os usuários podem aproximar o smartphone de qualquer terminal NFC compatível para resgatar cartões salvos na Carteira do Google.
Para usar o protocolo do Toque inteligente com seus cartões, é preciso estabelecer uma relação com um provedor de terminais compatíveis com o Toque inteligente.
APIs e SDK
API Google Wallet
A API Google Wallet é um serviço fornecido pelo Google que permite criar e emitir cartões para os usuários salvarem na Carteira do Google. Ela pode ser usada de várias maneiras diferentes, incluindo a API REST da Carteira do Google, o SDK da Carteira do Google para Android e o console da Carteira do Google.
API REST da Carteira do Google
A API REST da Carteira do Google é uma interface para criar e gerenciar cartões programaticamente com o envio de solicitações HTTP para a API Google Wallet.
Para usar a API REST da Carteira do Google, você também precisa de uma conta do Google Cloud para criar uma conta de serviço, que será usada para autenticar solicitações à API REST da Carteira do Google.
SDK da Carteira do Google para Android
O SDK da Carteira do Google para Android oferece um conjunto de métodos convenientes para trabalhar com a API Google Wallet nos apps Android, como a criação e a emissão de cartões.
Adicionar à Carteira do Google
Botão "Adicionar à Carteira do Google"
O botão "Adicionar à Carteira do Google" é um recurso aprovado pelo Google para apresentar um cartão ao usuário. Quando um usuário clica ou toca no botão, um link "Adicionar à Carteira do Google" é acionado para iniciar o fluxo de adição do cartão emitido à Carteira do Google.
É recomendável usar o botão "Adicionar à Carteira do Google" sempre que possível, já que os usuários já sabem interagir com esse elemento de interface conhecido.
Os recursos e as diretrizes para usar o botão estão disponíveis nas diretrizes da promoção de marca da API Google Wallet.
Link "Adicionar à Carteira do Google"
Com um link "Adicionar à Carteira do Google", você pode enviar um cartão para um usuário com um hiperlink normal. Isso pode ser usado em qualquer lugar onde seja possível usar hiperlinks, como e-mail, SMS, sites e apps para dispositivos móveis.
Para criar links "Adicionar à Carteira do Google", anexe um JWT assinado ao URL https://pay.google.com/gp/v/save/.
Conta emissora
Modo de demonstração
Quando você cria sua conta de emissor, ela fica no "modo de demonstração" até que o acesso de publicação seja aprovado. No modo de demonstração, é possível criar cartões, mas eles só podem ser emitidos para usuários com as funções "Administrador" ou "Desenvolvedor" da sua conta de emissor, ou para usuários que foram adicionados como contas de teste no console da Carteira do Google.
No "Modo de demonstração", o título de todos os cartões emitidos começará automaticamente com as palavras "[SOMENTE TESTE]" para indicar que eles servem apenas para testes.
Contas de teste
Quando sua conta de emissor estiver no "Modo de demonstração", se você quiser emitir cartões para qualquer usuário que não tenha as funções de "Administrador" ou "Desenvolvedor", será preciso adicioná-los como contas de teste no console da Carteira do Google. Os usuários inscritos como contas de teste poderão adicionar cartões emitidos por você à Carteira do Google. Isso é útil para testar os cartões com um público mais amplo no "Modo de demonstração".
Perfil da Empresa
Para criar uma conta de emissor para a API Google Wallet, configure um Perfil da Empresa ao se registrar no console do Google Pay e da Carteira. O Perfil da empresa fornece ao Google informações básicas sobre sua empresa ou organização. Ele precisa ser aprovado para acesso de publicação.
Acesso de publicação
Antes de emitir cartões que podem ser salvos por qualquer usuário na Carteira do Google, você precisa receber aprovação de publicação. Para receber a aprovação para publicar o acesso, você precisa criar pelo menos uma classe de cartões e ter um Perfil da Empresa completo. Os emissores que querem emitir cartões usando o SDK da Carteira do Google para Android também precisam enviar a impressão digital SHA-1 para o app.
Para solicitar acesso de publicação, acesse o console da Carteira do Google e clique no botão "Solicitar acesso de publicação". A equipe da Carteira do Google analisará sua solicitação e notificará você assim que você receber acesso de publicação.
Autenticação
JSON Web Token (JWT)
JSON Web Tokens são um padrão comumente usado do setor para transferir informações com segurança como um objeto JSON. Ao usar a API Google Wallet, codifique os detalhes do objeto de cartões que você quer usar para criar uma instância de cartão no formato JWT (pronunciado "jot") e envie esse JWT em uma solicitação para a API Google Wallet.
Para garantir a segurança, os JWTs são assinados em chaves secretas compartilhadas antes do envio à API Google Wallet. Se você estiver usando a API REST da Carteira do Google, a chave secreta de assinatura será a chave da sua conta de serviço do Google Cloud. Se você usa o SDK da Carteira do Google para Android, a chave secreta de assinatura é a impressão digital SHA-1 do app Android.
Conta de serviço
A conta de serviço do Google Cloud é um tipo especial de conta geralmente usada por um aplicativo ou carga de trabalho de computação, em vez de uma pessoa. No caso da API Google Wallet, uma conta de serviço é o que você usa para autenticar as solicitações enviadas à API REST da Carteira do Google.
As contas de serviço são criadas no console do Google Cloud. Para usar uma conta de serviço, você também precisa ativar a API Google Wallet no Console do Cloud para permitir que a conta de serviço faça solicitações à API REST da Carteira do Google.
Chave da conta de serviço
A chave de conta de serviço é a credencial que você vai usar para autenticar chamadas para a API REST da Carteira do Google. A chave da conta de serviço é considerada altamente confidencial e precisa ser mantida em particular, porque concede acesso a muitos dos recursos do emissor de cartão da sua conta usando a API REST da Carteira do Google, incluindo a criação de classes de cartão e objetos de cartão.
Impressão digital SHA-1
A impressão digital SHA-1 do seu certificado de assinatura de apps Android é a credencial que você usará para autenticar chamadas à API Google Wallet ao usar o SDK da Carteira do Google para Android. A impressão digital SHA-1 do seu certificado é gerada usando o Gradle ou o keytool. Para usar a impressão digital para autenticar suas solicitações, você precisa registrá-la no console da Carteira do Google.