Bypassing Violet Payments
Violet provides you with the ability to fully bypass any payments requirements during checkout. This includes capturing funds from shoppers, processing any merchant transfers, generating any distribution records, processing refunds, or tracking any payments related data; allowing you to leverage Violet’s Checkout capabilities while bypassing all order payment requirements. Violet refers to this as an EXTERNAL capture and EXTERNAL transfer scenario.
In this scenario, Channels assume all responsibility for facilitating payments between shoppers and merchants.
Enabling Payment Bypassing
In order to enable your app for complete bypassing of any payments requirements through Violet, you will need to reach out to Violet Support or file a support ticket through the Channel Dashboard. Violet allows this setting to be enabled at both the APP level, so that it applies to all merchants, or at the MERCHANT level, so that it applies to specific merchants during checkout.
Violet also requires that you subscribe to the ORDER_CANCELED, ORDER_REFUNDED, and ORDER_RETURNED webhooks, or the catchall ORDER_UPDATED webhook. This is to ensure that you can facilitate a refund back to the shopper when necessary.
Implementation Changes
Depending on your integration with Violet and the type of Checkout you use, learn about the changes you need to make to enable this in your flow:
Standard Checkout
Standard Checkout
When bypassing payments, the two major changes to Checkout are the following:
-
You do not need a payment intent created by Violet, so you can leave out the
wallet_based_checkoutflag from the Create Cart API or mark it as false. -
If you currently apply a payment method manually to the cart during Checkout, you can skip this call. This is the
/checkout/cart/:cart_id/paymentAPI.
The remainder of the calls made to Violet during the checkout flow all remain the same.
Even when payment bypassing is enabled, if a payment method is passed in during checkout, Violet WILL charge this payment method and use the Violet payments flow. You can use this as a fallback if there is an issue while you build out your payments logic.
Merchant Level Payment Bypassing
If you are looking to migrate from using the Violet payments stack to your own, you may want to bypass payments on a per merchant basis. You can do this through the following:
Adding the Merchant to the bypass list
Add the Merchant to the payment bypass list using the following API.
PUT apps/{app_id}/configuration/payments-bypass/{merchant_id}
This API will add the given merchant_id to the payments bypass list for this app_id. If the merchant doesn’t exist or you do not have permissions for this merchant an exception will be thrown.
Request
Request
Response
Response
Exceptions
Exceptions
Confirm that the merchant has been added for bypassing
Confirm that the merchant has been added by calling the following API
GET apps/{app_id}/configuration/payments-bypass
This API will fetch the list of MerchantPaymentBypassRecord s associated to this app_id .
Request
Request
Response
Response
Go through Violet Checkout
Go through the Violet checkout flow with the following modifications
-
Do NOT include the
wallet_based_checkoutflag in the Create Cart call, if you are currently using payment intent based payment method. -
Do NOT call the Apply Payment method during the checkout process, if you are manually applying a payment method to the cart.
-
During submission, include the following body, where
app_order_idis theorder_idfrom your system.
Orders that have products from multiple merchants must either
all be payment-bypassed merchants
or
all Violet-based payment merchants.
If not, an UnsupportedMerchantPaymentsException will be thrown.
To delete a merchant from the payment bypass list, you can call DELETE apps/{app_id}/configuration/payments-bypass/{merchant_id} or simply include payment methods to the order during checkout. If a payment method is included, Violet will honor that payment method.
DELETE apps/{app_id}/configuration/payments-bypass/{merchant_id}
This API will remove the given merchant_id from the payments bypass list for this app_id. If the merchant doesn’t exist or isn’t present in this list, an exception will be thrown.
Request
Request
Response
Response
Exceptions
Exceptions
When Violet receives a Refund for an Order that bypassed our payments flow, we emit a notification and expect the Shopper and Merchant to be refunded by you. In order to receive notifications, please subscribe to the ORDER_REFUNDED webhook. You are able to view refunds that come for Orders, even if the payment was handled externally, through GET orders/{order_id}/refunds. A sample response for an external refund is as follows:
Quick Checkout
Quick Checkout
Direct Order Submission
Direct Order Submission
Bypassing Violet Payments
Violet provides you with the ability to fully bypass any payments requirements during checkout. This includes capturing funds from shoppers, processing any merchant transfers, generating any distribution records, processing refunds, or tracking any payments related data; allowing you to leverage Violet’s Checkout capabilities while bypassing all order payment requirements. Violet refers to this as an EXTERNAL capture and EXTERNAL transfer scenario.
In this scenario, Channels assume all responsibility for facilitating payments between shoppers and merchants.
Enabling Payment Bypassing
In order to enable your app for complete bypassing of any payments requirements through Violet, you will need to reach out to Violet Support or file a support ticket through the Channel Dashboard. Violet allows this setting to be enabled at both the APP level, so that it applies to all merchants, or at the MERCHANT level, so that it applies to specific merchants during checkout.
Violet also requires that you subscribe to the ORDER_CANCELED, ORDER_REFUNDED, and ORDER_RETURNED webhooks, or the catchall ORDER_UPDATED webhook. This is to ensure that you can facilitate a refund back to the shopper when necessary.
Implementation Changes
Depending on your integration with Violet and the type of Checkout you use, learn about the changes you need to make to enable this in your flow:
Standard Checkout
Standard Checkout
When bypassing payments, the two major changes to Checkout are the following:
-
You do not need a payment intent created by Violet, so you can leave out the
wallet_based_checkoutflag from the Create Cart API or mark it as false. -
If you currently apply a payment method manually to the cart during Checkout, you can skip this call. This is the
/checkout/cart/:cart_id/paymentAPI.
The remainder of the calls made to Violet during the checkout flow all remain the same.
Even when payment bypassing is enabled, if a payment method is passed in during checkout, Violet WILL charge this payment method and use the Violet payments flow. You can use this as a fallback if there is an issue while you build out your payments logic.
Merchant Level Payment Bypassing
If you are looking to migrate from using the Violet payments stack to your own, you may want to bypass payments on a per merchant basis. You can do this through the following:
Adding the Merchant to the bypass list
Add the Merchant to the payment bypass list using the following API.
PUT apps/{app_id}/configuration/payments-bypass/{merchant_id}
This API will add the given merchant_id to the payments bypass list for this app_id. If the merchant doesn’t exist or you do not have permissions for this merchant an exception will be thrown.
Request
Request
Response
Response
Exceptions
Exceptions
Confirm that the merchant has been added for bypassing
Confirm that the merchant has been added by calling the following API
GET apps/{app_id}/configuration/payments-bypass
This API will fetch the list of MerchantPaymentBypassRecord s associated to this app_id .
Request
Request
Response
Response
Go through Violet Checkout
Go through the Violet checkout flow with the following modifications
-
Do NOT include the
wallet_based_checkoutflag in the Create Cart call, if you are currently using payment intent based payment method. -
Do NOT call the Apply Payment method during the checkout process, if you are manually applying a payment method to the cart.
-
During submission, include the following body, where
app_order_idis theorder_idfrom your system.
Orders that have products from multiple merchants must either
all be payment-bypassed merchants
or
all Violet-based payment merchants.
If not, an UnsupportedMerchantPaymentsException will be thrown.
To delete a merchant from the payment bypass list, you can call DELETE apps/{app_id}/configuration/payments-bypass/{merchant_id} or simply include payment methods to the order during checkout. If a payment method is included, Violet will honor that payment method.
DELETE apps/{app_id}/configuration/payments-bypass/{merchant_id}
This API will remove the given merchant_id from the payments bypass list for this app_id. If the merchant doesn’t exist or isn’t present in this list, an exception will be thrown.
Request
Request
Response
Response
Exceptions
Exceptions
When Violet receives a Refund for an Order that bypassed our payments flow, we emit a notification and expect the Shopper and Merchant to be refunded by you. In order to receive notifications, please subscribe to the ORDER_REFUNDED webhook. You are able to view refunds that come for Orders, even if the payment was handled externally, through GET orders/{order_id}/refunds. A sample response for an external refund is as follows:
Quick Checkout
Quick Checkout
Direct Order Submission
Direct Order Submission