A purchase flow (also known as shopping flow) represents the steps or actions a customer takes in order to complete payment for a purchase. In VTEX, the available purchase flows are:
- Payment App
The Transparent purchase flow is used when customers fill in payment information in the standard SmartCheckout template and complete the purchase without leaving the store. This is the most common option if you want to provide a seamless payment experience.
The Redirect purchase flow is used when customers confirm the payment option in the store and are then redirected to a different page to fill in payment information and complete the purchase.
This option is used when the partner needs a specific interaction with the customer that is not provided by the standard SmartCheckout template.
Some examples include: displaying a QR code for payment, filling in an application form, logging in to an external website.
For the connector that will use Redirect, there is no need to pass all the Test Suit tests, only the Redirect one.
The Payment App purchase flow is a flexible option used to allow customers to go through a custom payment experience without leaving the store.
This model applies to a large variety of payment methods thanks to its interaction with the Checkout API. However, Payment Apps must be developed and deployed using VTEX IO. For more information, check our Payment App guide.
The following operations define the patterns of interaction between the Payment Provider and the VTEX Payments Gateway:
- Cancellation or Refund
When a customer completes a purchase, this triggers the creation of a new payment request, starting with the Authorization operation.
As soon as the purchase is complete, the Payments Gateway sends a POST Create Payment request to the provider.
The payload is quite big, as it contains information such as the items in the cart, billing address, the order ID, payment methods, callbackURL, and others. More information about the endpoints and their payloads will be available in the Implementing a Payment Provider section.
After that, the provider should respond to the request. If the payment cannot be processed right the way, the transaction status changes to
undefined. That does not mean that the payment was canceled or denied, it is just being evaluated.
The system can retry the call asynchronously for seven days until the payment is indeed processed. During this period, VTEX will assume that the payment is “pending".
To break this cycle of asynchronous retries, there are two possible flows depending if the integration uses VTEX IO infrastructure or not:
- Without VTEX IO (developed in the partner's infrastructure): when the provider gets an updated payment status, it will use a notification endpoint from the
callbackURLparameter to change the payment status in the Gateway to
denied. Both responses end the authorization flow.
- With VTEX IO: when the provider gets an updated payment status, it will read the
callbackURLparameter to call a retry endpoint. Then, the Gateway makes another Create Payment request to obtain the new status defined by the provider, which will be
denied. Both responses end the authorization flow.
Mode-off status is a native reliability feature that allows VTEX to track the payment health and stability of their partners, ensuring that the system will not cancel orders due to instabilities.
When VTEX identifies consecutive errors in its payment partners’ integrations — more than five errors over the last five minutes — the mode-off status is activated to handle credit card transactions.
While the mode-off status is activated, all transactions that allow an asynchronous flow will be retained. During this period, the transaction remains in
This process takes an average of two hours and can hold up to two thousand requests. If the provider’s system returns to stability, the mode-off status is deactivated and our system will run processing reattempts for the transactions on standby.
For more information and frequently asked questions, refer to the Mode-Off: FAQ article in our Help Center.
The cancellation flow starts if the order is canceled for any reason. When an order is canceled, it activates the process to cancel the order’s payment as well.
In this case, there are two scenarios:
- The payment was approved and already settled.
- The payment was not approved.
When a payment is approved and already settled but canceled after that, VTEX makes the call POST Refund Payment to the payment provider. Also, the Payment Provider Protocol accepts partial refunds when necessary.
Regardless of the provider's response, VTEX will end the transaction with the status
VTEX sends the POST Cancel Payment request to the payment provider once there is no need to refund a payment that was not settled.
If the provider does not authorize the payment cancellation and returns a response with an
undefined status, the flow will run asynchronously for a day. If the provider does not respond after this period, the payment will be canceled.
Once the gateway authorizes the payment, VTEX sends the POST Settle Payment request to the provider. If the provider does not authorize the settlement right the way, the request will keep running asynchronously for a day.
During this period, when the provider responds to the call authorizing the settlement, VTEX’s platform changes the transaction status to
finished and completes the flow.
If after one day of retries the request fails, the payment will be canceled.
When using synchronous communication, VTEX will communicate with the payment provider during the purchase flow and this will determine whether the payment was approved or not.
When using asynchronous communication, VTEX will wait for a longer period of time for approval from the payment provider. This is the case of bank invoice (boleto bancário/Brazil), for example, where the shopper is expected to have a few days to pay for their order through their bank.
Depending on the payment method selected, three endpoints in the payment flow might use synchronous or asynchronous communication:
Since the selection of payment method depends on the customer, your provider must be prepared to receive multiple repeated requests in those endpoints.
Updated about 1 month ago