Ir para o conteúdo

Error Handling

The Payments application registers the status of the transaction, which can be consulted later, so that the app that integrates via the SDK is aware of the current status of the transaction and takes some action, if necessary.

During the transactional flow, unexpected failures may occur, such as terminal shutdown or sudden application closure due to an unhandled error. This can lead to inconsistencies in transaction resolution, and sometimes the app that integrates via the SDK needs to take some action to resolve this inconsistency.

The diagram below describes the application status flow and then suggestions on how to correct possible errors are presented.

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

In situations of unexpected failure (application closing by the terminal operator, for example, or Fatal Exception), both in the Payments application and in the application that integrates via SDK, we recommend adopting some strategies to ensure that pending issues are resolved and transactions are processed consistently:

  1. Immediately before calling startPaymentV2() (or other SDK functions), the application must persistently register the current time and the data it has of the transaction to be started, as well as a status that indicates that it will call startPaymentV2();
  2. Immediately upon receiving the callback (onSuccess or onError), the application must persistently register the current time, the data returned, and a status that indicates that it received the callback;
  3. If the flow is interrupted during a payment, the callback methods (onSuccess or onError) will not be called. a. The application that called startPaymentV2() can identify this case in two ways: i. When the Application starts its execution, it must check if there is a record of the startPaymentV2() call, without the corresponding callback being recorded. In this case, there may have been an unexpected interruption of the application itself, and there may or may not have been an unexpected interruption of Payments; ii. When detecting a long time (for example, 10 minutes) after the startPaymentV2() call, without the callback. In this case, there may have been an unexpected interruption of Payments; b. In these cases, for card payment transactions, the recommended behavior is as follows: i. Perform a query (see Query), passing the appTransactionId of the transaction; ii. If the paymentStatus is equal to CANCELLED, the transaction was undone by Payments and is already finalized. The application must consider that the transaction was not carried out. No action is required to resolve issues with Payments; iii. If the paymentStatus is equal to PENDING, the Application must request an undo through the cancelPayment() method. If the situation was identified as described in “i”, it may be that Payments has not been interrupted and the payment is still running, so the App must wait at least 10 minutes (from the time registered in “1”) before from calling cancelPayment(); iv. If the paymentStatus is equal to UNREACHABLE or PROCESSING, the transaction was interrupted even before being sent to the authorizer. The application must consider that the transaction was not carried out. No action is required to resolve issues with Payments; v. If the paymentStatus is equal to DENIED, the transaction was denied. The application must consider that the transaction was not carried out. No action is required to resolve issues with Payments; c. In these cases, for payment transactions with QR the recommended behavior is the following: i. Call the resolveQRCodePendencyV2() method, passing the intent's appTransactionId; ii. If qrCodeIntentStatus is equal to PENDING or CREATED, the app must continue querying until it receives a final status; iii. If the qrCodeIntentStatus is equal to CANCELLED, EXPIRED or DENIED, the application must consider that the transaction was not carried out. No action is required to resolve issues with Payments; iv. If qrCodeIntentStatus equals APPROVED, the application will receive transaction data and must process them. The application must assume that the transaction has taken place. No action is required to resolve issues with Payments.