Exemplo de fluxo completo: pagamento via API REST

Um pagamento feito por API envolve a obtenção da credencial, a chamada ao serviço, a leitura do resultado e a atualização do sistema da loja. Ver essas etapas em sequência ajuda a separar uma cobrança com resultado desconhecido de uma cobrança confirmada que ainda não aparece no sistema.

O fluxo do exemplo

No site de vendas, o pedido PED-0001 aguarda o pagamento. O integrador cobra esse pedido no gateway de pagamento nestes passos:

1. o integrador lê o pedido PED-0001 gravado pelo site de vendas;
2. o integrador verifica se tem um token válido e, quando não tem, obtém um token novo em POST /oauth/token, pelo fluxo client credentials;
3. o serviço de autorização devolve o token e a validade, que no gateway de pagamento é de 3600 segundos, uma hora;
4. o integrador monta o corpo da cobrança com os campos do contrato, como o número do pedido, os itens, o frete e o valor total;
5. o integrador envia POST /v1/pagamentos com o token no cabeçalho Authorization e com a chave de idempotência da operação;
6. o integrador lê o status HTTP, o corpo e o número da cobrança, e o código 201 confirma a criação da cobrança, enquanto o campo de situação informa se o pagamento está aprovado, pendente ou recusado;
7. o integrador registra no log a operação, a tentativa, o resultado e os identificadores;
8. o integrador atualiza o pedido no banco de dados local com o resultado ou agenda o acompanhamento da cobrança pendente.

Quando a cobrança fica pendente, o acompanhamento consulta GET /v1/pagamentos/PAG-0001 em intervalos ou recebe um aviso do gateway de pagamento, conforme o contrato, até o resultado final.

Uma integração com um PBM segue uma sequência parecida: o programa obtém o token, executa a pré-autorização do benefício e lê o retorno. A semelhança do fluxo não torna iguais os contratos, porque cada fornecedor define as próprias operações, os campos e os códigos.

A etapa de cada falha

A etapa em que a falha aparece orienta a investigação:

• uma falha registrada na obtenção do token aponta a credencial e o serviço de autorização;
• uma resposta de recusa aponta o motivo informado pelo gateway de pagamento;
• um tempo esgotado à espera da resposta da cobrança deixa o resultado desconhecido e exige a consulta da situação;
• uma aprovação confirmada no gateway de pagamento com o pedido ainda pendente na loja aponta a leitura da resposta e a atualização local.

O ponto em que o log termina não comprova o ponto em que a execução parou. A gravação do log pode ser parcial, a atualização pode acontecer depois, em outra etapa, e a tela pode estar mostrando dados antigos. A relação entre o pedido, a cobrança, a tentativa e a situação atual vem antes da conclusão.

A aprovação remota e a atualização local

O gateway de pagamento pode confirmar a cobrança PAG-0001, e a gravação local falhar logo depois. Nesse caso, uma cobrança nova não corrige a diferença e pode cobrar o cliente duas vezes. A correção começa pela confirmação do pedido, da conta, do ambiente e do valor e segue pelo procedimento de recuperação da atualização local.

Uma integração bem construída guarda o número da cobrança remota e uma pendência recuperável quando não consegue concluir todas as etapas. O acompanhamento consulta a situação ou recebe o aviso do fornecedor e aplica o resultado no banco local com proteção contra repetição.

A reconciliação compara a situação no fornecedor com a situação na loja e registra as diferenças. Quando a consulta ainda não encontra a cobrança, o alcance e o prazo de disponibilização da consulta são conferidos antes da conclusão de que não houve cobrança. Quando o pagamento está confirmado, a evidência fica preservada para a regularização do pedido pelo procedimento autorizado.