Padrões de protocolo

A API segue um conjunto de padrões de APIs HTTP e oferece suporte idempotência para facilitar um processo integração total.

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. O URL completo é criado adicionando o ID da conta do integrador de pagamentos do autor da chamada ao fim. 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 vai adicionar 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ê está de implementação terão 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. Você não deve incluir o parâmetro ID da conta do integrador de pagamentos (PIAID) nos URLs hospedados.

Ambientes sandbox e de produção

O Google hospeda as APIs Standard Payments no sandbox (para desenvolvimento e testes) e produção. Solicitações no ambiente de sandbox do Google não resultam em responsabilidade financeira real. A sandbox e ambientes de produção são completamente separados e não compartilham chaves ou informações da transação.

O Google espera que seu sandbox esteja sempre disponível, já que usaremos o sandbox para testar mudanças e novos recursos.

Caminho base do sandbox do Google

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

Observação: caso sua integração já tenha sido lançada e chame o método https://billpaynotification.sandbox.googleapis.com host, você pode continuar faça isso. As novas integrações devem chamar o URL "vgw.sandbox.google.com" host

Caminho base de produção do Google

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

Observação: caso sua integração já tenha sido lançada e chame o método https://billpaynotification.googleapis.com host, você pode continuar a fazer isso. As novas integrações precisam chamar o "vgw.googleapis.com" host

Neste guia, serão usados os endpoints de produção.

Tipo de conteúdo e codificação

Os payloads de mensagens que usam criptografia PGP precisam usar o tipo de conteúdo application/octet-stream; charset=utf-8. Os corpos das solicitações de PGP precisam ser enviada usando a codificação base64url, conforme definido no rfc4648 §5. Os payloads de mensagens que usam criptografia JWE precisam usar o tipo de conteúdo application/jose; charset=utf-8 A opção de serialização compacta suportado por JWE/JWS lida com a codificação do corpo da solicitação final.

Códigos de status HTTP

As APIs Standard Payments foram projetadas para retornar um código de status HTTP 200. para todas as solicitações que podem ser processadas pelo servidor. Isso inclui solicitações bem-sucedidas e recusadas da perspectiva das empresas lógica do aplicativo. As solicitações que não podem ser processadas não devem resultar em uma Código de status HTTP 200, já que eles representam um erro entre o Google e o parceiro. Em vez disso, a resposta da API deve usar o status HTTP apropriado códigos abaixo com um objeto ErrorResponse opcional.

Erros HTTP e motivos
400	BAD REQUEST O cliente especificou um argumento inválido. Ele também pode ser retornado se a operação for rejeitada porque o sistema não está em um estado necessário para a execução da operação. Use se novas tentativas da solicitação não forem bem-sucedidas até que o estado do sistema foi explicitamente corrigido. Por exemplo, se uma solicitação de reembolso falha porque ele faz referência a uma captura que não existe, a nova tentativa não terá sucesso. até que a captura exista no sistema de integradores. Observação:não use BAD_REQUEST (400) para situações em que um erro de aplicativo apropriado está disponível. Para exemplo, moedas incorretas devem retornar ACCOUNT_DOES_NOT_SUPPORT_CURRENCY com o código 200 se o a resposta padrão tem esse campo ou tipo enumerado.
401	UNAUTHORIZED A solicitação não possui credenciais de autenticação válidas para o 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, normalmente devido a um problema de simultaneidade, como falhas de verificação do sequenciador, cancelamentos de transação etc.
412	PRECONDITION FAILED Esse código deve ser usado em situações em que uma chave de idempotência está sendo reutilizados com parâmetros diferentes.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS Alguns recursos do sistema se esgotaram.
499	CANCELLED A operação foi cancelada, normalmente pelo autor da chamada.
500	INTERNAL ERROR Erros internos. Isso significa que algumas invariantes esperadas pelo sistema foi corrompida.
501	UNIMPLEMENTED A operação não foi implementada, suportada ou ativada neste serviço.
503	UNAVAILABLE O serviço não está disponível no momento. É muito provável que seja um e pode ser corrigido ao tentar novamente.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED O prazo expirou antes que a operação fosse concluída. Para operações que alterar o estado do sistema, esse erro poderá ser retornado mesmo se o foi concluída com sucesso. Por exemplo, uma resposta bem-sucedida de um servidor poderia ter atrasado tempo suficiente para que o prazo final e depois ela expira.

IDempotência da solicitação

A idempotência da solicitação é uma estratégia central usada na API Standard Payments APIs usadas para garantir que as interações de sistema entre o Google e os parceiros sejam robustos e tolerantes a falhas. Solicitações Idempotentes são aquelas que podem ser enviada várias vezes, mas ter o mesmo efeito de uma única solicitação. Essa estratégia facilita a consistência posterior entre os sistemas ao tornar novas tentativas seguras, permitindo que nossos sistemas cheguem a um acordo quanto à o estado atual do recurso.

Nossa API usa idempotência para:

• reduzir problemas de reconciliação, tornando todas as ações facilmente rastreáveis e auditáveis.
• evitar disputas, garantindo que várias solicitações idênticas de mesmo cliente não resultam em um estado final diferente.
• minimizar o estado permitindo que as solicitações sejam compreendidas de forma isolada, permitindo para melhorar o desempenho e a capacidade de processamento removendo a carga do servidor causada a retenção de dados.
• evitar a necessidade de campos adicionais para indicar se uma solicitação é uma nova tentativa.

.

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

Exemplos

Exemplo 1: conectividade perdida antes do recebimento da resposta

Cenário:

1. O Google envia uma solicitação 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 é enviada com os mesmos parâmetros (o mesmo ID e detalhes da solicitação, mas atualizados requestTimestamp) para o servidor do integrador.

Resultado:

Nesse caso, o servidor do integrador precisa enviar a mesma resposta em etapa 2, já que todos os parâmetros, exceto responseTimestamp, são iguais. O efeito colateral ocorre apenas uma vez, na etapa 2. A etapa 4 não tem efeito colateral.

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

Cenário:

1. O banco de dados do servidor do integrador está inativo para manutenção.
2. O Google envia uma solicitação ao 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 atualizou requestTimestamp). Observe que os IDs das duas solicitações deve ser o mesmo.
7. O servidor do integrador recebe a solicitação e retorna um código de status OK com resposta completa.

Resultado:

Nesse caso, o servidor do integrador precisa processar a solicitação na etapa 7 e não retornar HTTP 503 (UNAVAILABLE). Em vez disso, o servidor do integrador deve processar a solicitação e retornar OK com a mensagem adequada. Embora o sistema é UNAVAILABLE O Google pode fazer solicitações repetidas semelhantes a etapa 2. Cada solicitação deve resultar em uma mensagem semelhante à etapa 3. As etapas 6 e 7 ocorrerão depois.

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 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 tenta enviar a mesma solicitação. mas alguns dos parâmetros são diferentes.

Resultado:

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