Ir para o conteúdo

Algoritmo recomendado para Aplicações integradas

A aplicação de Pagamentos registra o status da transação que pode ser consultado posteriormente, para que o app que se integra via SDK tenha conhecimento do estado atual da transação e tome alguma ação, caso necessário.

Durante o fluxo transacional, podem ocorrer falhas inesperadas, como o desligamento do terminal ou fechamento repentino da aplicação devido a algum erro não tratado. Isto pode gerar inconsistências na resolução da transação, sendo preciso que em alguns momentos o app que se integra via SDK realize algumas ações para resolver essa inconsistência.

O diagrama abaixo descreve o fluxo dos status da aplicação e em seguida são apresentadas sugestões de como corrigir possíveis erros.

assets/images/Diagrama Payments assets/images/Diagrama QR Code

Em situações de falha inesperada (fechamento da aplicação pelo operador do terminal ou Fatal Exception, por exemplo), tanto na aplicação de Pagamentos quanto na aplicação que se integra via SDK, recomendamos adotar algumas estratégias para garantir que as pendências sejam resolvidas e as transações sejam processadas de forma consistente:

  1. Imediatamente antes de chamar startPaymentV2() (ou outras funções do SDK), a aplicação deve registrar de forma persistente o horário atual e os dados que possui da transação a ser iniciada, appTransactionId, bem como um status que indique que irá chamar startPaymentV2();
  2. Imediatamente ao receber o callback (onSuccess ou onError), a aplicação deve registrar de forma persistente o horário atual, os dados retornados, e um status que indique que recebeu o callback;
  3. Caso ocorra interrupção do fluxo em um pagamento, os métodos de callbacks (onSuccess ou onError) não serão chamados.

a. A aplicação que chamou startPaymentV2() pode identificar este caso de duas formas:

  • i. Quando a Aplicação iniciar sua execução, deve verificar se existir registro de chamada de startPaymentV2(), sem que tenha havido registro do callback correspondente. Nesse caso pode ter havido interrupção inesperada da própria aplicação, podendo ou não ter havido também interrupção inesperada de Payments;

  • ii. Ao detectar um longo tempo (por exemplo, 10 minutos) após a chamada de startPaymentV2(), sem que tenha havido o callback. Nesse caso pode ter havido interrupção inesperada de Payments;

b. Nesses casos, para transações de pagamento com cartão o comportamento recomendado é o seguinte:

  • i. Realizar uma consulta (vide Consulta), passando o appTransactionId da transação;

    • ii. Caso o paymentStatus seja igual a CANCELLED, a transação foi desfeita por Payments e já está finalizada. A aplicação deve considerar que a transação não foi realizada. Não é necessária nenhuma ação para resolver pendências com Payments;

  • iii. Caso o paymentStatus seja igual a PENDING, a Aplicação deve solicitar desfazimento através do método cancelPayment(). Se a identificação da situação ocorreu da forma descrita em “i”, pode ser que Payments não tenha sido interrompida e ainda esteja executando o pagamento, por isso o App deve esperar pelo menos 10 minutos (desde o tempo registrado em “1”) antes de chamar cancelPayment();

  • iv. Caso o paymentStatus seja igual a UNREACHABLE ou PROCESSING, a transação foi interrompida antes mesmo de ser enviada ao autorizador. A aplicação deve considerar que a transação não foi realizada. Não é necessária nenhuma ação para resolver pendências com Payments;

  • v. Caso o paymentStatus seja igual a DENIED, a transação foi negada. A aplicação deve considerar que a transação não foi realizada. Não é necessária nenhuma ação para resolver pendências com Payments;

c. Nesses casos, para transações de pagamento com QR o comportamento recomendado é o seguinte:

  • i. Chamar o método resolveQRCodePendencyV2(), passando o appTransactionId da intenção;

  • ii. Caso o qrCodeIntentStatus seja igual a PENDING ou CREATED, o app deve continuar consultando (chamando resolveQRCodePendencyV2()) até receber um status final;

  • iii. Caso o qrCodeIntentStatus seja igual a CANCELLED, EXPIRED ou DENIED, a aplicação deve considerar que a transação não foi realizada. Não é necessária nenhuma ação para resolver pendências com Payments;

  • iv. Caso o qrCodeIntentStatus seja igual a APPROVED, a aplicação receberá os dados da transação e deverá processá-los. A aplicação deve considerar que a transação foi realizada. Não é necessária nenhuma ação para resolver pendências com Payments.