Padrões de protocolo

A API segue um conjunto de padrões da API HTTP e permite a idempotência para facilitar uma integração mais robusta.

URLs hospedados pelo Google

A documentação de cada método hospedado pelo Google fornece um URL base, que inclui o nome do método e o número da versão principal. Para criar o URL completo, adicione o ID da conta do integrador de pagamentos do autor da chamada ao final. Por exemplo, a documentação do método echo hospedado pelo Google especifica o URL:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo

Se o ID da conta do integrador de pagamentos do autor da chamada for INTEGRATOR_1, ele seria adicionado ao final do URL para formar:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1

Observação: a página de documentação do endpoint do método específico que você estiver implementando terá o URL mais preciso para seu caso.

URLs hospedados por parceiros

A documentação de cada método de API hospedado por parceiro fornece um URL base, que inclui o nome do método e o número da versão principal. Não inclua o ID da conta do integrador de pagamentos (PIAID) nos URLs que você hospeda.

Ambientes sandbox e de produção

O Google hospeda as APIs One Time Payment Code no sandbox (para fins de desenvolvimento e teste) e na produção. As solicitações no ambiente sandbox do Google não resultam em nenhuma responsabilidade financeira. Os ambientes sandbox e de produção são completamente separados e não compartilham chaves nem informações de transação.

O Google espera que seu sandbox esteja disponível de forma consistente, já que usaremos o sandbox para primeiro testar alterações e recursos novos.

Caminho base do sandbox do Google

https://vgw.sandbox.google.com/secure-serving/gsp/

Observação: se a sua integração já foi lançada e está chamando o host https://billpaynotification.sandbox.googleapis.com, você pode continuar dessa forma. As novas integrações precisam chamar o host "vgw.sandbox.google.com".

Caminho base de produção do Google

https://vgw.googleapis.com/secure-serving/gsp/

Observação: se a sua integração já foi lançada e está chamando o host https://billpaynotification.googleapis.com, você pode continuar dessa forma. As novas integrações precisam chamar o host "vgw.googleapis.com".

Neste guia, usaremos os endpoints de produção.

Tipo de conteúdo e codificação

Os payloads das mensagens que usam a criptografia PGP precisam usar o tipo de conteúdo application/octet-stream; charset=utf-8. Os payloads de mensagens que usam criptografia JWE precisam usar o tipo de conteúdo application/jose; charset=utf-8. Os corpos das solicitações precisam ser enviados usando a codificação base64url, conforme definido em rfc4648 §5.

Códigos de status HTTP

As APIs One Time Payment Code foram projetadas para retornar um código de status HTTP 200 para todas as solicitações que podem ser processadas pelo servidor, incluindo solicitações bem-sucedidas e recusadas da perspectiva dos negócios ou da lógica do aplicativo. As solicitações que não podem ser processadas não devem resultar em um código de status HTTP 200, já que elas representam um erro entre o Google e o parceiro. Em vez disso, a resposta da API precisa usar os códigos de status HTTP apropriados abaixo com um objeto ErrorResponse opcional.

Erros do HTTP e motivos
400	BAD REQUEST O cliente especificou um argumento inválido. Isso também poderá ser retornado se a operação for rejeitada porque o sistema não está no estado necessário para a execução da operação. Use se as novas tentativas da solicitação não forem bem-sucedidas até que o estado do sistema seja explicitamente corrigido. Por exemplo, se uma solicitação de reembolso falhar porque se refere a uma captura inexistente, uma nova tentativa não terá êxito até que a captura exista no sistema de integradores. Observação: BAD_REQUEST (400) não deve ser usado para situações em que um erro de aplicativo apropriado está disponível. Por exemplo, moedas incorretas deverão retornar ACCOUNT_DOES_NOT_SUPPORT_CURRENCY com o código 200 se a resposta padrão tiver esse campo ou uma enumeração.
401	UNAUTHORIZED A solicitação não tem credenciais válidas de autenticação para a operação. Por exemplo, assinaturas inválidas ou desconhecidas devem retornar 401.
403	FORBIDDEN / PERMISSION DENIED O autor da chamada não tem permissão para executar a operação especificada.
404	NOT FOUND Algumas entidades solicitadas, como pagamento ou usuário, não foram encontradas.
409	CONFLICT / ABORTED A operação foi cancelada, geralmente devido a um problema de simultaneidade, como falhas na verificação do sequenciador, cancelamentos de transações etc.
412	PRECONDITION FAILED Esse código deve ser usado em situações em que uma chave de idempotência está sendo reutilizada com parâmetros diferentes.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS Alguns recursos do sistema foram esgotados.
499	CANCELLED A operação foi cancelada, geralmente pelo autor da chamada.
500	INTERNAL ERROR Erros internos. Isso significa que algumas variantes esperadas pelo sistema subjacente foram interrompidas.
501	UNIMPLEMENTED A operação não foi implementada, permitida ou ativada neste serviço.
503	UNAVAILABLE O serviço não está disponível no momento. Essa é provavelmente uma condição temporária e poderá ser corrigida ao tentar novamente.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED O prazo expirou antes que a operação fosse concluída. Para operações que alteram o estado do sistema, este erro pode ser retornado mesmo que a operação tenha sido concluída com sucesso. Por exemplo, uma resposta bem-sucedida de um servidor pode ter sido atrasada tempo suficiente para que o prazo expirasse.

Idempotência da solicitação

A idempotência da solicitação é uma estratégia central usada nas APIs One Time Payment Code para garantir que as interações do sistema entre o Google e os parceiros sejam robustas e tolerantes a falhas. As solicitações idempotentes são aquelas que, potencialmente, podem ser enviadas várias vezes, mas têm o mesmo efeito que uma única solicitação. Essa estratégia facilita a consistência posterior entre os sistemas ao tornar as tentativas seguras, permitindo que nossos sistemas entrem em acordo sobre o status do recurso.

Nossa API usa idempotência para:

• reduzir os problemas de reconciliação, tornando todas as ações facilmente rastreáveis e auditáveis.
• evitar disputas ao garantir que várias solicitações idênticas do mesmo cliente não resultem em um estado final diferente.
• minimizar o status permitindo que as solicitações sejam compreendidas isoladamente, permitindo melhor desempenho e removendo a carga do servidor causada pela retenção de dados.
• evitar a necessidade de campos adicionais para indicar se uma solicitação é nova.

Observação: os resultados de erros nunca devem ser armazenados em cache ou retornados de forma idempotente. Além disso, novas tentativas automatizadas para erros precisam usar uma estratégia de espera exponencial.

Exemplos

Exemplo 1: conectividade perdida antes da resposta ser recebida

Cenário:

1. o Google envia uma solicitação de captura ao integrador.
2. o servidor do integrador recebe essa solicitação e a processa com sucesso.
3. o servidor do Google fica sem energia antes de receber a resposta na etapa 2.
4. a energia do servidor do Google é restaurada e a mesma solicitação de captura é enviada com os mesmos parâmetros (o mesmo ID e detalhes da solicitação, mas com requestTimestamp atualizado) para o servidor do integrador.

Resultado:

nesse caso, o servidor do integrador precisa responder com a mesma resposta da etapa 2, já que todos os parâmetros, exceto responseTimestamp, são iguais. O usuário é cobrado apenas uma vez, na etapa 2. A etapa 4 não tem impacto monetário no usuário.

Exemplo 2: solicitação enviada para um servidor em manutenção

Cenário:

1. o banco de dados do servidor do integrador está indisponível para manutenção.
2. o Google envia uma solicitação para o integrador.
3. o integrador retorna corretamente o código de status UNAVAILABLE.
4. o servidor do Google recebe a resposta e programa uma nova tentativa.
5. o banco de dados do servidor do integrador volta a ficar on-line.
6. O Google reenvia a solicitação da etapa 2 (mesmo ID e detalhes da solicitação, mas requestTimestamp atualizado). Os IDs de solicitação para as duas solicitações devem ser os mesmos.
7. o servidor do integrador recebe a solicitação e retorna um código de status OK com a resposta completa.

Resultado:

nesse caso, o servidor do integrador precisa processar a solicitação na etapa 7 e não retornar HTTP 503 (UNAVAILABLE). O servidor do integrador deve processar totalmente a solicitação e retornar OK com as mensagens apropriadas. Embora o sistema seja UNAVAILABLE, o Google pode fazer solicitações repetidas semelhantes à etapa 2. Cada solicitação deve resultar em uma mensagem semelhante à etapa 3. As etapas 6 e 7 ocorrerão posteriormente.

Exemplo 3: a mensagem repetida não corresponde à mensagem inicial devido a um erro de recuperação

Cenário:

1. o Google envia uma solicitação para o integrador.
2. o servidor do integrador recebe essa solicitação e a processa com sucesso.
3. o servidor do Google fica sem energia antes de receber a resposta na etapa 2.
4. a energia do servidor do Google é restaurada e tenta enviar a mesma solicitação, mas alguns dos parâmetros são diferentes.

Resultado:

Nesse caso, o servidor do integrador responderá com um código de erro HTTP 412 (PRECONDITION FAILED), que indica ao Google que há um erro neste sistema.