FOP em dinheiro

Visão geral

O Google Standard Payments é compatível com FOPs (formas de pagamento) com base em dinheiro, como compras em lojas de conveniência (como uma 7-Eleven). Em um nível superior, um usuário que quer pagar por produtos gera um número de referência pelo integrador de pagamentos. Em seguida, o usuário leva esse número de referência a uma loja de conveniência, quiosque ou banco e paga por ele.

Adição de pagamento
1) O usuário adiciona uma forma de pagamento.
Escolha onde pagar
2) Depois, ele escolhe onde pagar
Instruções de pagamento
3) Por fim, ele recebe instruções de pagamento.

Conceitos e terminologia

Símbolos e Convenções

As palavras-chave “PRECISA”, "NÃO PODE", "OBRIGATÓRIO" "SHALL", "NÃO DEVE" "DEVERIA", "NÃO DEVERIA", "RECOMENDADO", "MAIO", e "OPTIONAL" nestes documentos devem ser interpretados conforme descrito em RFC 2119.

Carimbos de data/hora

Todos os carimbos de data/hora são representados em milissegundos desde a época Unix (1o de janeiro de 1970) em UTC.

Exemplo:

  • 23 de abril de 2019 20:23:25 GMT = 1556051005000 milissegundos
  • 16 de agosto de 2018 12:28:35 GMT = 1534422515.000 milissegundos

Valores

Os valores monetários nessa API estão em um formato chamado "micros", é um padrão no Google. Micros são um formato de precisão fixa 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:

  • US$1,23 = 1230.000 microUSD
  • US$0,01 = 10.000 microUSD

Idempotência

Todas as chamadas de método nessa API precisam ter comportamento idempotente. O Google vai repetir as solicitações esporadicamente para garantir que as transações estejam no mesmo estado nos dois lados. Os integradores não podem tentar reprocessar solicitações que já foram processadas. Em vez disso, a resposta do processamento bem-sucedido deve ser informada. Todos os métodos têm um RequestHeader comum que contém um requestId. Esse requestId é a chave de idempotência para todas as chamadas.

Qualquer resposta não terminal (uma não HTTP 200 bem-sucedida) não pode ser processada de forma idempotente. Portanto, uma solicitação que antes recebeu um erro 400 (solicitação inválida/pré-condição com falha), quando chamada uma segunda vez, não pode retornar 400 de maneira idempotente e precisa ser reavaliada. Na reavaliação, ele pode retornar um erro 400 ou ser processado com êxito.

Para mais informações sobre idempotência, consulte este guia detalhado.

Integrador

Uma empresa que usa a plataforma de pagamentos do Google. Pode ser interna (própria), como o YouTube ou o Google AdWords, ou uma empresa externa (3P) que quer integrar o próprio serviço para trabalhar com o ecossistema do Google.

Forma

Forma de pagamento. Isso é mais geral do que um instrumento. Visa, MasterCard e PayPal são FOPs.

Instrumento

Uma instância específica de uma forma de pagamento feita por um cliente específico. Por exemplo, o cartão de crédito de um usuário ou a conta do PayPal. Uma FOP tokenizada para um determinado cliente também é um instrumento, porque é uma instância de uma forma de pagamento para esse cliente, armazenada com segurança em nosso sistema.

Token

Uma representação, no sistema do Google, da forma de pagamento de um usuário específico. Como ele contém todas as informações necessárias para fazer uma compra, um token também é um instrumento. Isso pode incluir informações como um número de conta que um usuário tem com o integrador.

Principais fluxos

O Google usa dois fluxos principais para criar e pagar esses números de referência:

  1. Gerar fluxo do número de referência.
  2. Fluxo do Número de referência de pagamento.

Posteriormente, a reconciliação e a liquidação das compras resultantes serão tratadas pelo fluxo de remessa.

O diagrama abaixo ilustra cada um desses fluxos.

Visão geral da forma de pagamento em dinheiro

Visão geral das formas de pagamento em dinheiro

Os dois primeiros fluxos são descritos em mais detalhes nas seções a seguir. Consulte a página Fluxo de remessa se quiser saber mais sobre esse fluxo.

Gerar número de referência

O objetivo do fluxo para gerar número de referência é criar e trocar um identificador (número de referência) que o Google e o integrador podem usar para identificar uma compra. O usuário pode usar esse número de referência em uma loja de conveniência, quiosque ou banco para concluir a compra. Esse identificador é gerado pelo integrador na solicitação do Google, chamando o método generateReferenceNumber. A solicitação para gerar um número de referência inclui um valor e uma descrição da transação.

O diagrama a seguir ilustra como um número de referência é gerado e enviado ao cliente com instruções.

Fluxo de geração do número de referência

Número de referência para geração de dinheiro

Veja uma lista dos objetos e o que eles representam:

  • Usuário: é a pessoa que quer pagar por algo usando essa forma de pagamento.
  • interface do Google: é a interface em que o usuário faz a compra. Pode ser pela Web ou por um app.
  • Servidor do Google: o servidor de back-end no Google que solicita a geração do número de referência e cria instruções de pagamento para o usuário.
  • Servidor do integrador de pagamentos: o servidor de back-end do integrador de pagamentos que acompanha os detalhes do pagamento e gera o número de referência.

Esse fluxo começa com o usuário que quer usar a forma de pagamento em dinheiro.

  1. O usuário acessa a interface do Google, que envia uma solicitação de um número de referência.
  2. A interface do Google envia uma mensagem ao servidor do Google informando que ele precisa de um número de referência (getReferenceNumber).
  3. O Servidor do Google solicita que o Servidor do integrador de pagamentos gere um número de referência (generateReferenceNumber).
  4. O Servidor do integrador de pagamentos gera e envia o número de referência ao Servidor do Google.
  5. O servidor do Google cria instruções de pagamento para acompanhar o número de referência. Em seguida, ele envia essas informações para a interface do Google.
  6. A interface do Google envia essas instruções e o número de referência ao usuário.

Observações sobre números de referência

Os números de referência só podem ser pagos uma vez e podem ser cancelados por meio do processo de cancelamento de número de referência. Além disso, os números de referência precisam ser alfanuméricos e oferecer suporte a vários formatos de exibição.

Além de exibir o número de referência, as interfaces do Google podem, opcionalmente, representar o número de referência no formato Code 128 (um formato de código de barras). Outros formatos de código de barras podem ser aceitos mediante solicitação.

Número de referência do pagamento

O usuário usará esse número de referência em uma loja de conveniência, quiosque ou banco para identificar a compra pela qual quer pagar. O integrador precisa pedir que o usuário confirme a compra que está sendo paga mostrando o valor, a data e a descrição da transação antes do pagamento.

Quando o usuário opta por pagar, ele deve pagar o valor total e pagar apenas uma vez. Esta API não suporta pagamentos em excesso ou insuficientes com um único número de referência. Também não é possível realizar vários pagamentos para um único número de referência.

Depois que o usuário pagar, o integrador precisará notificar imediatamente o Google de que esse número de referência foi pago pelo método referenceNumberPaidNotification. Ao chamar esse método segundos depois de o usuário fazer o pagamento físico, o integrador permite que o usuário receba as mercadorias rapidamente. Essa chamada poderá ser adicionada a uma fila se a rede estiver inativa.

Após o pagamento, o número de referência e o valor serão incluídos no extrato de remessa enviado em T+2 dias.

Veja um diagrama de sequência que ilustra o pagamento de um número de referência.

Fluxo do número de referência de pagamento

Fluxo do número de referência de pagamento

Os objetos no diagrama representam o seguinte:

  • Usuário: é a pessoa que quer pagar por algo usando essa forma de pagamento.
  • Loja de conveniência: o local onde o usuário faz um pagamento usando o número de referência e as instruções fornecidas, como uma loja de conveniência.
  • Servidor do integrador de pagamentos: o servidor de back-end do integrador de pagamentos que monitora os detalhes do pagamento.
  • Servidor do Google: o servidor de back-end no Google que solicita a geração do número de referência e cria instruções de pagamento para o usuário.

Esse fluxo começa com o usuário que vai a uma loja de conveniência para fazer um pagamento de acordo com as instruções fornecidas.

  1. O usuário vai a uma loja de conveniência para fazer um pagamento.
  2. Depois que a transação for concluída, a loja de conveniência vai notificar o integrador de pagamentos sobre o pagamento.
  3. O servidor do integrador de pagamentos envia uma mensagem de sucesso para o armazenamento de conveniência.
  4. A Loja de conveniência informa que a transação foi um sucesso para o Usuário e que os produtos serão entregues ao Usuário em breve.
  5. O servidor do integrador de pagamentos envia uma mensagem ao servidor do Google informando que o número de referência foi pago (referenceNumberPaidNotification). Esta etapa não pode bloquear a etapa 4.
  6. O servidor do Google responde com uma mensagem de sucesso ao servidor do integrador de pagamentos.
.

Cancelar número de referência

Os números de referência podem ser cancelados pelo Google. Se o Google cancelar um número de referência, o método cancelReferenceNumber será chamado. Após o retorno desta chamada, não será possível pagar esse número de referência, e o integrador precisará recusar o pagamento desse número. Após a conclusão dessa chamada, todas as chamadas futuras para referenceNumberPaidNotification vão falhar.

Se o processo de pagamento já tiver sido iniciado, por exemplo, se o usuário tiver inserido o número de referência em um quiosque, mas ainda não tiver feito o pagamento, o integrador vai retornar um código de resposta HTTP 423 com ErrorResponse contendo USER_ACTION_IN_PROGRESS.

Próximo: fluxo de remessa