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

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_checkout flag from the Create Cart API or mark it as false.

//Create cart using Violet Payments

{
  "base_currency": "USD",
  "wallet_based_checkout": true,
  "skus": [
      {
      "sku_id": {{default_sku_id}},
      "quantity": 5
    }
  ]
}

//Create cart while bypassing payments

{
  "base_currency": "USD",
  "skus": [
      {
      "sku_id": {{default_sku_id}},
      "quantity": 5
    }
  ]
}

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/payment API.

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

Response

Exceptions

Exceptions in the following scenarios:
- App does not exist
- Merchant does not exist
- App does not have permissions for this Merchant or App
- The Merchant has already been added to the list

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

Response

Go through Violet Checkout

Go through the Violet checkout flow with the following modifications

Do NOT include the wallet_based_checkout flag 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_id is the order_id from your system.
```
{
    "app_order_id": 12345
}
```

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

Response

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:

[
    {
        "id": 119,
        "order_id": 142,
        "bag_id": 145,
        "merchant_id": 6,
        "app_id": 10000,
        "transaction_id": 87,
        "amount": 385900,
        "reason": "",
        "refund_currency": "JPY",
        "status": "EXTERNAL",
        "skus": [
            {
                "id": 126,
                "refund_id": 119,
                "bag_id": 145,
                "quantity_refunded": 1,
                "external_id": "43598413463851",
                "order_sku_id": 133
            }
        ],
        "date_created": "2023-01-26T15:44:08+0000",
        "date_last_modified": "2023-01-26T15:44:09+0000",
        "external_id": "942270382379",
        "errors": []
    }
]

Quick Checkout

Direct Order Submission

Introduction

Getting Started

Checkout

Payments

Violet Connect

Relay

Product Info

Support

Enabling Payment Bypassing

Implementation Changes

Merchant Level Payment Bypassing

Introduction

Getting Started

Checkout

Payments

Violet Connect

Relay

Product Info

Support

​Enabling Payment Bypassing

​Implementation Changes

Enabling Payment Bypassing

Implementation Changes