ID da conta
O ID da conta é enviado de volta do servidor do integrador durante o fluxo de associação. Ele é usado para ajudar o Google a identificar a conta subjacente de duas maneiras. Primeiro, identificar vários instrumentos que usam a mesma conta de usuário para avaliar riscos e fraudes. Ele também é usado pelos agentes de atendimento ao cliente do Google para identificar a conta. Esse valor precisa identificar de forma exclusiva a conta do usuário nas solicitações de associação. Além disso, ele precisa ser imutável na conta específica e ser identificável pelo usuário.
Por exemplo, se um integrador usar um endereço de e-mail para identidade, ele poderá ser o endereço de e-mail. No entanto, se o integrador usar um endereço de e-mail para fazer login, mas esse endereço puder ser alterado, o endereço de e-mail não será uma opção adequada para o ID da conta. Seja qual for a escolha, o valor dela precisa ser o mesmo em várias tentativas de associação com a mesma identidade de usuário do integrador de pagamentos.
Pacote de aplicativo Android (APK)
O formato de arquivo de pacote usado pelo sistema operacional Android para distribuição e instalação de apps para dispositivos móveis.
Controle de versões da API
Esta especificação é compatível com o controle de versões. As versões compatíveis são configuradas no servidor do Google. Ao mudar da versão N para a M (em que M é uma versão principal maior que N), o integrador precisa oferecer suporte a N e M até que o Google verifique se todo o tráfego foi migrado para M. As versões são identificadas de maneira diferente com base no contexto. As APIs do Android e WebRedirect vão transmitir a versão da API como um parâmetro para a solicitação. As chamadas de servidor para servidor transmitem a versão como uma parte do caminho do URL.
As versões não são fixas por fluxo. Portanto, durante a migração da N para M, um integrador pode ver uma captura com a versão M e um reembolso com a versão N para a mesma transação. Durante a associação, o integrador pode receber uma solicitação de autenticação da versão M com uma solicitação de associação da versão N.
ID de associação
O associationID identifica a associação entre a conta do cliente e o instrumento do Google. O associationId é muito semelhante à GPT. Na verdade, ele tem a mesma vida útil de uma GPT e tem uma cardinalidade individual em uma GPT. O
associationId é diferente da GPT na sensibilidade. A GPT é um token confidencial usado para pagamentos. O associationId é um identificador público que
representa a mesma relação, mas não é tão confidencial por natureza.
O associationId é transmitido para o integrador de pagamentos durante
associateAccount. Esse mesmo valor é transmitido para o integrador durante a reautenticação. Isso permite que o integrador tenha contexto sobre qual conta precisa
ser autenticada. Se o ID de associação for transmitido, a mesma conta identificada durante a associação original precisará ser preenchida e autenticada novamente.
Espera-se que o integrador de pagamentos armazene todos os IDs de associação e os associe a uma conta de integrador específica durante todo o ciclo de vida do contrato entre o integrador e o Google.
ID da solicitação de autenticação
Os métodos refreshToken, associateAccount e (opcionalmente) de captura usam uma
referência a uma autenticação. Essa referência está na forma do requestId da autenticação específica a que o Google se refere. Esse campo é usado pelo integrador de pagamentos para verificar se o método realmente foi executado por uma autenticação bem-sucedida.
Os métodos de captura podem ter um requestId de autenticação preenchido. Isso acontece
em dois casos. Se o Google autenticar o usuário pouco antes de uma captura, ele
preencherá o campo de autenticação requestId. Além disso, o Google geralmente autentica
o usuário no momento da configuração, quando um calendário de pagamento automatizado é definido. O Google
grava a autenticação requestId nessa programação e envia o
requestId com todas as capturas associadas a essa programação específica.
Os integradores de pagamentos precisam armazenar todas as requestIds de autenticação por 30
dias. Se um integrador de pagamentos quiser auditar a requestIds de autenticação
que pode estar presente em uma solicitação de captura, incluindo as incluídas nos calendários de
pagamentos, ele precisará armazenar todas as requestIds de autenticação durante
o ciclo de vida do contrato entre o integrador e o Google.
Empresa
Uma empresa é um conceito definido na configuração e no contrato do Google. Uma empresa define a relação entre o integrador e o Google. Chaves PGP e (opcionalmente) CAs raiz SSL estão associadas à empresa. O mais importante é que uma empresa seja associada a um ou mais IDs de conta do integrador de pagamentos. As GPTs criadas em uma empresa funcionam principalmente para todos os IDs de conta de integradores de pagamentos dentro da empresa. Algumas exceções são aplicáveis. Por exemplo, se a GPT estiver associada a uma conta denominada em uma moeda (e não aceita taxas de câmbio) e estiver tentando fazer uma compra em um ID da conta do integrador de pagamentos em uma moeda diferente.
Forma de pagamento (FOP, na sigla em inglês)
Todas as transações incluem uma ou mais formas de pagamento (FOPs, na sigla em inglês), como cartão de crédito ou transferência eletrônica de fundos, que são usadas pelos usuários para pagar o Google por produtos ou serviços, ou pelo Google para pagar usuários, no caso de usuários do Google AdSense e desenvolvedores do Google Play. Formas de pagamento também são frequentemente chamadas de Instrumentos de Pagamento, Instrumentos e Formas de pagamento.
Token de pagamentos do Google (GPT)
A GPT é um valor codificado em base64 aleatório e seguro para a Web gerado pelo servidor do Google no momento da associação e transmitido para o servidor do integrador. A GPT é um identificador privado que representa o vínculo entre a conta do usuário com o integrador e o instrumento do Google. A GPT é um token que substitui as credenciais do usuário ou um ID de conta. Esse token é usado durante os fluxos de compra para identificar a conta para crédito ou débito e é secreto para ambas as partes. A GPT nunca pode ser enviada em texto não criptografado e precisa ser criptografada para garantir a privacidade.
A GPT é diferente de associationId porque associationId não é protegida
e é transmitida livremente por meios públicos (URLs, conexões não seguras). A GPT é conhecida apenas pelo Google e pelo integrador.
Espera-se que o integrador de pagamentos armazene todas as GPTS e as associe a uma conta de integrador específica durante o ciclo de vida do contrato entre o integrador e o Google.
Idempotência
Uma operação idempotente pode ser aplicada várias vezes sem alterar o resultado ou ter novos efeitos colaterais além da aplicação inicial da operação. Normalmente, a idempotência usa uma "chave" para identificar a mesma
solicitação. Todas as solicitações definidas entre os dois servidores usam uma chave de idempotência
definida no cabeçalho da solicitação. O cabeçalho da solicitação tem um ID que é
usado como uma chave de idempotência. O ID da solicitação é globalmente exclusivo. As solicitações idempotentes precisam ser exatamente o mesmo corpo JSON com uma exceção. O requestTimestamp será diferente para cada solicitação. Essa é uma distinção
importante. requestTimestamp é a hora em que o servidor enviou essa solicitação. E é único por tentativa. Isso ajuda a reduzir a capacidade de ataques repetidos.
Da mesma forma, uma resposta idempotente precisa ter exatamente o mesmo corpo JSON, mas o
responseTimestamp será diferente para cada resposta.
Todos os métodos de servidor para servidor, exceto o método Echo, precisam ser idempotentes. As solicitações de autenticação para a IU do integrador (seja Android ou Web) não são idempotentes.
Para exemplos de comportamento idempotente, consulte o documento de referência.
Identificador (ID)
Os identificadores representam uma transação ou comunicação entre o integrador de pagamentos e o Google.
Instrumento
O instrumento representa uma forma de pagamento armazenada e associada a um único cliente do Google. Exemplos de instrumentos:
- Um número de cartão de crédito registrado
- Uma conta bancária e um número identificador
Os usuários podem ter vários instrumentos associados à identidade do Google.
Micros
Os valores monetários nesta API são representados com um formato chamado "micros", um padrão do Google. Micros são um formato de precisão fixa e baseado em números inteiros. Para representar um valor monetário em micros, multiplique o valor da moeda padrão por 1.000.000.
Exemplo:
- USD 1,23 = 1230.000 micro USD
- USD 0,01 = 10.000 micro USD
Integrador de pagamentos
O integrador externo que processa pagamentos de uma transação do usuário.
ID da conta do integrador de pagamentos
Esse identificador representa restrições em relação ao contrato entre o Google e o integrador. O ID da conta do integrador é gerado pelo Google e atribuído ao integrador durante a configuração. Normalmente, isso é chamado de "MID". Todas as solicitações e respostas precisam incluir esse ID. Esse identificador é opaco e nunca precisa ser analisado. O formato desse identificador não é consistente em todos os documentos de identificação emitidos.
Esse identificador nunca muda durante o ciclo de vida de uma transação. No caso de uma captura e um reembolso, o mesmo identificador é usado.
As restrições do ID da conta do integrador são definidas pelo próprio contrato. Geralmente, as restrições estão relacionadas ao faturamento. Por exemplo, um integrador aceita CAD e MXN como faturas em USD, mas exige que as transações em EUR sejam faturadas em EUR. Nesse caso, dois IDs diferentes de conta do integrador de pagamentos vão ser usados, um para o faturamento em USD e outro para o faturamento em EUR.
O identificador pode ser descontinuado em favor de novos identificadores. No caso em que
um identificador for descontinuado, o Google vai parar de iniciar capturas para esse
identificador. No entanto, o integrador precisa honrar os reembolsos das transações feitas
nesse identificador por um ano a partir da última inicialização de captura (iniciação
de captura definida como a requestTimestamp encontrada no requestHeader).
PII
Informações de identificação pessoal (PII) são informações que identificam pessoalmente um indivíduo e quaisquer outros dados que podem ser razoavelmente vinculados a essas informações pelo Google, como nome, endereço de e-mail, endereço de correspondência ou número de telefone de um usuário, sozinhos ou combinados
Solicitar ID
O requestId identifica toda a comunicação entre o Google e o integrador de
pagamentos.
informações confidenciais de identificação pessoal (SPII, em inglês)
Informações sensíveis de identificação pessoal (SPII, na sigla em inglês) são um subconjunto de informações de identificação pessoal (PII, na sigla em inglês) que apresentam um alto risco ao usuário em casos de comprometimento ou uso indevido. As SPII geralmente têm requisitos restritivos de tratamento e armazenamento impostos por entidades legais, regulatórias ou de conformidade.
Token
Os tokens adicionam uma camada extra de segurança quando credenciais sensíveis, como PII ou SPII, são trocadas entre o Google e o integrador.
Endereço do usuário
No momento da criação do instrumento, o Google verifica se o usuário é um cliente do Google Payments. Isso não depende de você ser cliente do Google. Para ser cliente do Google Payments, precisamos do endereço de faturamento do usuário. Algumas agências regulatórias exigem que saibamos o endereço completo do usuário, enquanto outros exigem um subconjunto desse endereço.
Se o integrador de pagamentos tiver um endereço registrado para esse usuário, o Google vai querer receber esse endereço durante o fluxo de associação para preencher automaticamente o formulário de endereço para o usuário. O usuário tem a opção de alterar o endereço pré-preenchido. Preencher automaticamente o endereço do usuário diminui o atrito na adição de um instrumento e aumenta a taxa de conversão de usuários que adicionam esses instrumentos.
Se o endereço for compartilhado, o Google também o usará como um cálculo no modelo de risco. Isso permite que o mecanismo de risco do Google entenda o endereço que o usuário diz que é cobrado enquanto o compara com o local do IP em que o usuário está atualmente.
O compartilhamento de endereços é puramente uma otimização. É normal que alguns integradores não tenham um endereço de faturamento para o usuário ou não possam compartilhar esse endereço.
Codificação Base64 segura para a Web
O padrão de codificação especificado na seção 5 do RFC 4648, Codificação Base 64 com URL e alfabeto seguro de nome de arquivo, também conhecido como codificação Base64 segura para a Web ou "base64url". É o mesmo que a codificação base64 com alfabeto seguro de URL e nome de arquivo da seção 4 do RFC 3548. Todos os valores criptografados e assinados precisam ser codificados usando esse padrão.