FOP em dinheiro

Informações gerais

O Google Standard Payments é compatível com formas de pagamento (FOPs, na sigla em inglês) baseadas em dinheiro, como compras em lojas de conveniência (como uma 7-Eleven). De modo geral, um usuário que quer pagar por produtos gera um número de referência com o 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 o número de referência.

Adicionar uma forma de pagamento
1) O usuário adiciona uma forma de pagamento.
Escolha onde pagar
2) Em seguida, escolhem onde pagar
Instruções de pagamento
3) Por fim, eles recebem instruções de pagamento.

Conceitos e terminologia

Símbolos e convenções

As palavras-chave "PRECISA", "NÃO PODE", "OBRIGATÓRIO", "DEVE", "NÃO DEVE", "DEVE", "NÃO DEVE", "RECOMENDADO", "PODE" e "OPCIONAL" nestes documentos devem ser interpretadas conforme descrito na RFC 2119 (em inglês).

Marcações de tempo

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 = 155.6051005.000 milissegundos
  • 16 de agosto de 2018, 12h28min35s GMT = 1534422515000 milissegundos

Valores

Os valores monetários nesta API estão no formato "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

Idempotência

Todas as chamadas de método nessa API precisam ter comportamento idempotente. O Google repetirá as solicitações esporadicamente para garantir que as transações estejam no mesmo estado em ambos os lados. Os integradores não podem tentar reprocessar solicitações já processadas. A resposta de 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 que não seja de terminal (uma operação sem HTTP 200) não pode ser processada de maneira idempotente. Portanto, uma solicitação que anteriormente recebeu um erro 400 (solicitação inválida/pré-condição com falha), quando chamada pela segunda vez, não deve retornar 400 de maneira idempotente, ela precisa ser reavaliada. Na reavaliação, ela pode retornar um erro 400 ou ser processada.

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

Integrador

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

Forma de pagamento

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 realizada por um cliente específico. Por exemplo, o cartão de crédito de um usuário ou a conta do PayPal dele. Uma FOP tokenizada para um cliente específico também é um instrumento, porque é uma instância de uma forma de pagamento para aquele cliente, armazenada com segurança no 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, o token também é um instrumento. Isso pode incluir informações como um número de conta que o usuário tem no integrador.

Fluxos de chaves

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

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

Mais tarde, a reconciliação e a liquidação das compras resultantes são processadas pelo fluxo de remessa.

O diagrama abaixo ilustra cada um desses fluxos.

Visão geral da forma de pagamento em dinheiro

Visão geral de alto nível da FOP de dinheiro

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

Gerar número de referência

O objetivo do fluxo de geração de 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 a pedido 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.

Gerar fluxo de número de referência

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

Veja a seguir uma lista dos objetos e do que eles representam:

  • Usuário: a pessoa que quer pagar por algo usando essa forma de pagamento.
  • IU 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 do 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 monitora os detalhes do pagamento e gera o número de referência.

Esse fluxo começa com o usuário que deseja usar essa 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 é necessário 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 para o 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 fluxo do número de referência de cancelamento. Além disso, os números de referência precisam ser alfanuméricos e compatíveis com vários formatos de exibição.

Além de exibir o número de referência, as interfaces do Google também podem 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 de pagamento

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

Se o usuário optar pelo pagamento, ele precisará pagar o valor total e pagar apenas uma vez. Esta API não suporta pagamentos excessivos ou insuficientes em um único número de referência. Também não é possível fazer vários pagamentos para um único número de referência.

Depois que o usuário paga, o integrador precisa notificar imediatamente o Google que esse número de referência foi pago pelo método referenceNumberPaidNotification. Ao chamar esse método alguns segundos depois do usuário pagar fisicamente, o integrador permite que o usuário receba os produtos rapidamente. Essa chamada poderá ser adicionada a uma fila se a rede estiver fora do ar.

Depois do 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 o 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 do 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 efetuar um pagamento de acordo com as instruções fornecidas a ele.

  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 êxito para a loja de conveniência.
  4. A loja de conveniência informa que a transação foi concluída para o usuário e que os produtos serão entregues a ele em breve.
  5. O servidor do integrador de pagamentos envia uma mensagem para o servidor do Google informando que o número de referência foi pago (referenceNumberPaidNotification). Essa 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 deste número. Após a conclusão dessa chamada, todas as chamadas futuras para referenceNumberPaidNotification falharão.

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.

A seguir: fluxo de remessa