Using Stripe Elements with Violet

Stripe Elements is a set of prebuilt UI components for securely collecting and handling payment information in web applications. It allows developers to easily integrate a customizable payment form while ensuring compliance with security standards like PCI DSS.

Violet integrates with Stripe Elements to let you easily use all their features while processing payment during Checkout through Violet. This guide will walk you through the steps to integrate Stripe Elements with Violet, depending on which Checkout flow you are using.

Pre-requisites

Install up Stripe.js

Install the Stripe.js React libraries and the Stripe JS loader from the npm public registry:

npm install --save @stripe/react-stripe-js @stripe/stripe-js

Checkout Flows

Depending on the Checkout flow you use, add support for Stripe Elements by following the guides below.

To integrate with Stripe Elements you will need to do the following:

Creating a Cart

The general process to Create a Cart remains the same, however, you will need to add the following flag to the request body:

{
    "wallet_based_checkout": true
}

This ensures that the Cart that is creates includes a payment intent in the response that can be used with Stripe Elements.

Accessing the Payment Intent Client Secret

In order to configure Stripe Elements in your UI, you will need to use the Payment Intent Client Secret on the Order. This can be accessed from the Cart response, within payment_transactions.

"payment_transactions": [
        {
            "id": 84808,
            "order_id": 123981,
            "payment_provider": "STRIPE",
            "amount": 900,
            "currency": "USD",
            "capture_status": "REQUIRES_PAYMENT_METHOD",
            "capture_method": "AUTOMATIC",
            "transfer_status": "PENDING",
            "transfer_method": "AUTOMATIC",
            "metadata": {
                "payment_intent_client_secret": "pi_3QpCRx2eXDTnoxH51SOBjwot_secret_0VYreFpdISo01L0K26HPSXUWt",
                "payment_intent_id": "pi_3QpCRx2eXDTnoxH51SOBjwot"
            },
            "errors": [],
            "date_created": "2025-02-05T17:31:45+0000",
            "date_last_modified": "2025-02-05T17:31:45+0000",
            "status": "REQUIRES_PAYMENT_METHOD"
        }
    ]

Add and configure the Payment Element

To use the Stripe Payment element, wrap your checkout page in a Stripe Elements provider. This is where you will also use the Stripe Key and Payment Intent Client Secret provided in the Order response.

import React from 'react';
import ReactDOM from 'react-dom';
import { Elements } from '@stripe/react-stripe-js';
import { loadStripe } from '@stripe/stripe-js';

import CheckoutForm from './CheckoutForm';

// Make sure to call `loadStripe` outside of a component’s render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('{{STRIPE_KEY_FROM_ORDER_RESPONSE}}', {});

function App() {
  const options = {
    clientSecret: '{{PAYMENT_INTENT_CLIENT_SECRET_FROM_ORDER_RESPONSE}}',

    // Fully customizable with appearance API.
    appearance: {
      /*...*/
    },
  };

  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutForm />
    </Elements>
  );
}

ReactDOM.render(<App />, document.getElementById('root'));

Add the Payment Element to your Checkout Form

In your checkout form, render the Stripe PaymentElement component:

import React from 'react';
import { PaymentElement } from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  return (
    <form>
      <PaymentElement />
      <button>Submit</button>
    </form>
  );
};

export default CheckoutForm;

The Payment Element renders a dynamic form that allows your customer to pick a payment method. Depending on their payment method, the form automatically requests that the customer fills in all necessary payment details.

You can customize the Payment Element to match the design of your site by passing the appearance object into options when creating the Elements provider.

By default, the Payment Element only collects necessary billing address details. In cases where you need to collect full billing address, like for calculating tax for digital goods and services, you can use the Address Element in Billing mode.

Confirm Payment

When your shopper is ready to complete their cart and submit their order, you will need to confirm the payment. Note that you should only confirm a payment as the final step before calling /submit on a cart to Violet since no other action can be taken on the cart that alters the cart total (like setting shipping methods or adding skus) after confirming the payment.

Add a listener to your Checkout form and then call Stripe.confirmPayment to attach the payment method your shopper provided to the payment intent sent by Violet and authorize the payment. Stripe will automatically request all the information that is needed for that payment method.

The Stripe.confirmPayment call does not charge the credit card. Instead, it only authorizes the amount that needs to be paid and ensures there are sufficient funds. Charges are only captured once an order has successfully been placed in the external merchant store.

If there are issues during submission, the shopper’s card is never charged. The authorization will fall off their card within a few business days.

import React from 'react';
import {
  useStripe,
  useElements,
  PaymentElement,
} from '@stripe/react-stripe-js';

export default function CheckoutForm() {
  const stripe = useStripe();
  const elements = useElements();

  const handleSubmit = async (event) => {
    // We don't want to let default form submission happen here,
    // which would refresh the page.
    event.preventDefault();

    if (!stripe || !elements) {
      // Stripe.js has not yet loaded.
      // Make sure to disable form submission until Stripe.js has loaded.
      return;
    }

    const result = await stripe.confirmPayment({
      elements,
      confirmParams: {
        // Make sure to change this to your payment completion page
        return_url: '<http://localhost:3000>',
      },
    });

    stripePaymentMethodHandler(result);
  };

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      <button type="submit" disabled={!stripe}>
        Submit Payment
      </button>
    </form>
  );
}

If a successful result is returned from the call to Stripe, a payment method has successfully been attached to the payment intent that Violet provided.

Submit the Cart to Violet

You can submit the order in the stripePaymentMethodHandler method called above. This is where you will call Violet Checkout submit:

const stripePaymentMethodHandler = async (result) => {
  if (result.error) {
    // Show error in payment form
  } else {
    // Otherwise submit order to Violet
    const res = await fetch('{{baseUrl}}/checkout/cart/:cart_id/submit', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        app_order_id: //orderId for this order in your system,
      })
    });

    const orderResponse = await res.json();

    handleServerResponse(orderResponse);
  }
}

Optional: Further Payment Requirements

If there are further actions required for your customer during the payment process, such as 3D secure authentication, Violet will respond with the following status on the order:

{
    "payment_status": "REQUIRES_ACTION",
}

If this is the case, you can use the same payment_intent_client_secret and the Stripe.handleNextAction method to request the additional information from the shopper.

const handleServerResponse = async (orderResponse) => {
  if (response.error) {
    // Show error from server on payment form
  } else if (orderResponse.payment_status.requires_action) {
    // Use Stripe.js to handle the required next action
    const { error: errorAction, paymentIntent } = await stripe.handleNextAction(
      {
        clientSecret: orderResponse.payment_intent_client_secret,
      }
    );

    if (errorAction) {
      // Show error from Stripe.js in payment form
    } else {
      // Actions handled, submit order to Violet once again
      const res = await fetch('{{baseUrl}}/checkout/cart/:cart_id/submit', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          app_order_id: //orderId for this order in your system,
        })
      });
    }
  } else {
    // No actions needed, show success message
  }
};

Unlike Standard and Quick Checkout, Carts are not created during Direct Order Submission. As a result, to use Stripe Elements with Direct Order Submission, Violet only requires you to send in a payment method. There are two payment methods Violet currently accepts:

Payment Intent

When using Direct Order Submission with Payment Intents, you can directly interact with the Stripe API and Stripe Elements to create a Payment Intent and attach a Payment Method to it. Once you have the Payment Intent ID and its in a state where it can be captured, you can include it in the Create Order API request body.

{
  "payment_method": {
      "type": "PAYMENT_INTENT",
      "payment_provider": "STRIPE",
      "token": "pi_3QpCRx2eXDTnoxH51SOBjwot"
  }
}

Payment Method Token

To use Direct Order Submission with a Stripe Card Token, you can generate a token using Stripe Elements as described here. Once you have a token, you can include it in the Create Order API request body.

{
  "payment_method": {
      "type": "SINGLE_USE_CARD_TOKEN",
      "payment_provider": "STRIPE",
      "token": "tok_i1s2h8a9nyg1ukrju12h31kj212kh"
  }
}

To learn more about Direct Order Submission, review our complete DOS guide

Introduction

Getting Started

Checkout

Payments

Violet Connect

Relay

Product Info

Support

Pre-requisites

Checkout Flows

Introduction

Getting Started

Checkout

Payments

Violet Connect

Relay

Product Info

Support

​Pre-requisites

​Checkout Flows

Pre-requisites

Checkout Flows