Direct order submission enables channels who calculate their own tax and shipping rates to submit fully composed orders in a single request. For most commerce platforms, the prices you provide in the order submission request will override the built-in pricing engine of the platform. This ensure’s that the merchants system of record and automated customer communication (ex. order confirmation emails) remain accurate.

This guide goes through the steps needed to compose an Order and directly submit it to the merchant through Violet.

​
Retrieve SKUs from the Violet Catalog

Retrieve SKUs you are able to sell through the Violet Catalog APIs

​
Capture Shopper Information

Capture Shopper information through your UI elements. At a minimum, you will need the following:

  1. First Name
  2. Last Name
  3. Email
  4. Shipping Address

You will need to submit this information as a part of the Create Order endpoint. Optionally, if “Billing Address” is different to the “Shipping Address”, those details can also be added to the request body.

​
Estimate Cart Prices

Estimate Cart prices using the Estimate Cart endpoint. You will need to input the information that was previously collected from the Shopper.

  • Estimate Cart

    POST /carts/estimate

{
  "base_currency": "USD",
  "skus": [
    {
      "quantity": 2,
      "sku_id": 123
    }
  ],
  "shipping_address": {
    "city": "Seattle",
    "state": "WA",
    "postal_code": "<string>",
    "country": "US",
    "address_1": "<string>",
    "address_2": "<string>"
  }

  • Sample Response

    {
  "estimated_carts": [
    {
      "merchant_id": 123,
      "platform": "SHOPIFY",
      "base_currency": "USD",
      "sub_total": 1,
      "shipping_total": 1,
      "discount_total": 1,
      "total": 1,
      "skus": [
        {
          "quantity": 1,
          "sku_id": 80455,
          "name": "Lunar Lemonade - 10 oz.",
          "price": 9999,
          "merchant_id": 10064,
          "external_id": "42519630413999",
          "available": true,
          "requires_shipping": true,
          "product_type": "PHYSICAL",
        }
      ],
      "available_shipping_methods": [
        {
          "carrier": "OTHER",
          "label": "Teleportation",
          "price": 10000
        }
      ],
      "has_shipping_methods": true,
      "external_error_messages": [
        "<string>"
      ]
    }
  ]
}

​
Adding a Payment Method

If you are bypassing payments (i.e. not using Violet to orchestrate payments and payouts), you do not need to include a payment method. When creating an Order in the next step, simply leave out the payment_method in the request.

Violet supports accepting two forms of payment method when creating Orders.

  1. Single-use Card Tokens
  2. Pre-authorized Stripe Payment Intents

​
Creating a Single-use Card Token

Capture Shopper Credit Card information using Stripe JS Elements and create a Stripe Token:

Alternatively, if you’re using a different user input form to collect and store shopper credit card information, you can call the Stripe API directly to create a token

For the token to be accepted during Checkout, you’ll need to ensure that its created using the Stripe Public Key that is associated with the same Stripe account being used for payment orchestration. If this is Violet’s Account, please reach out to us for this key.

​
Using a pre-authorized Payment Intent

This payment method can only be used if you’ve connected your pre-existing Stripe Platform account to Violet. Learn more about this here.

1

Create a payment intent with Stripe

Start with creating a payment intent in Stripe using the Payment Intents API. This must be done on the same account you used to onboard with Violet Payments. Ensure that the amount and currency, match that of the Order you will be creating. Additionally, Violet requires that the payment intent is marked for manual capture. For example:

 curl https://api.stripe.com/v1/payment_intents \
     -u "sk_test_<REDACTED>:" \
     -d amount=120000 \
     -d currency=usd \
     -d capture_method=manual

Store the payment intent ID that Stripe returns in the response.

2

Add a payment method to the Payment Intent

A payment method must be added to the payment intent prior to it being used when creating an Order. To do this, you can use Stripe.js Elements, or the update Payment Intents API.

Alternatively, you can modify the call in the previous step to include a payment method on payment intent create. For example:

 curl https://api.stripe.com/v1/payment_intents \
     -u "sk_test_<REDACTED>:" \
     -d amount=120000 \
     -d currency=usd \
     -d payment_method=pm_card_visa \
     -d capture_method=manual
3

Authorize the payment intent

Authorize the payment intent by calling the Confirm Payment Intent API. This ensures that this is not a fraudulent payment method and that there are sufficient funds for this purchase. Alternatively, if Stripe.js Elements were used to capture the shopper payment method, Stripe may have automatically authorized the shopper payment method. Once a payment intent is authorized, its amount cannot change.

4

Include the payment intent when calling Create Order

When creating an Order using the API below, include the payment intent as a payment method. For example:

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

​
Creating the Order

Call the Violet Create Order endpoint with the information collected above to create an Order:

The following information must be included to create an Order:

  1. First Name
  2. Last Name
  3. Email
  4. Shipping Address
  5. Bag(s)

For a multi-merchant Order, multiple bags must be created in the Order payload. Each Bag must contain items from only one merchant and have its own shipping method.

  • Sample Request

    POST /orders

{
 "payment_method": {
   "type": "SINGLE_USE_CARD_TOKEN",
   "payment_provider": "STRIPE",
   "token": "tok_1289y1ishakj12h31kj212kh"
 },
  "order": {
    "app_order_id": "mario-test-1",
    "customer": {
      "first_name": "Ultra",
      "last_name": "Violet",
      "email": "super@mar.io"
    },
    "bags": [
      {
        "skus": [
          {
            "sku_id": 80455,
            "price": 100000
          }
        ],
        "shipping_method": {
          "carrier": "OTHER",
          "label": "Teleportation",
          "price": 10000
        },
        "tax_total": 10000
      }
    ],
    "shipping_address": {
      "address_1": "2815 Elliott Ave",
      "address_2": "Unit 100",
      "city": "Seattle",
      "state": "WA",
      "country": "US",
      "postal_code": "98121"
    },
    "billing_address": {
      "address_1": "200 West Street",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "postal_code": "10282"
    },
    "currency": "USD"
  }
}

billing_address is optional in the request above. If left out, the shipping_address will be used as the billing_address for the Order.

If Order submission succeeds, Violet will respond with a completed Cart.

  • Sample Response

    {
    "id": 54609,
    "token": "f9bd116404dc4441838a94f31a942d5f",
    "errors": [],
    "app_id": 10193,
    "developer_id": 10122,
    "customer": {
        "first_name": "Ultra",
        "last_name": "Violet",
        "email": "super@mar.io",
        "name": "Ultra Violet"
    },
    "bags": [
        {
            "id": 64579,
            "order_id": 54609,
            "merchant_id": 10064,
            "status": "ACCEPTED",
            "fulfillment_status": "PROCESSING",
            "financial_status": "PAID",
            "skus": [
                {
                    "id": 60509,
                    "merchant_id": 10064,
                    "app_id": 10193,
                    "product_id": "815b064726de41d9a21de4bfc029416f",
                    "sku_id": 80445,
                    "external_id": "42519630413999",
                    "name": "Lunar Lemonade - 10 oz.",
                    "brand": "Space Drinks",
                    "thumbnail": "https://cdn.shopify.com/s/files/1/0621/1849/4383/files/wealthy_lunar_lemonade_4a9c0731-8758-4847-91e1-d6d37d6ace22.png",
                    "quantity": 1,
                    "price": 100000,
                    "weight": 3.0,
                    "available": true,
                    "status": "PROCESSING",
                    "product_type": "PHYSICAL",
                    "line_price": 100000
                }
            ],
            "shipping_method": {
                "type": "FLAT_RATE_PRICE",
                "carrier": "OTHER",
                "label": "Teleportation",
                "price": 10000,
                "custom": false,
                "id": 21839,
                "merchant_id": 10064
            },
            "taxes": [
                {
                    "order_id": 54609,
                    "merchant_id": 10064,
                    "state": "WA",
                    "rate": 10.0,
                    "amount": 10000
                }
            ],
            "sub_total": 100000,
            "shipping_total": 10000,
            "tax_total": 10000,
            "total": 120000,
            "taxes_included": false,
            "transactions": [],
            "external_checkout": false,
            "commission_rate": 0.0,
            "date_created": "2024-06-28T20:31:56+0000",
            "date_last_modified": "2024-06-28T20:31:56.000+00:00",
            "remorse_period_ends": "2024-07-28T20:31:56+0000",
            "currency": "USD",
            "external_currency": "USD",
            "channel": "MARKETPLACE",
            "app_order_id": "ishan-test-1",
            "platform": "SHOPIFY",
            "fulfillments": [],
            "discounts": [],
            "wallet_based_checkout": false,
            "bag_id": 64579,
            "bag_status": "ACCEPTED",
            "merchant_name": "Space Drinks"
        }
    ],
    "shipping_address": {
        "name": "Ultra Violet",
        "city": "Seattle",
        "state": "WA",
        "country": "US",
        "postal_code": "98121",
        "type": "BILLING",
        "address_1": "2815 Elliott Ave",
        "address_2": "Unit 100",
        "first_name": "Ultra",
        "last_name": "Violet"
    },
    "billing_address":{
        "name": "Ultra Violet",
        "city": "New York",
        "state": "NY",
        "country": "US",
        "postal_code": "10282",
        "type": "BILLING",
        "address_1": "200 West Street",
        "first_name": "Ultra",
        "last_name": "Violet"
    },
    "payment_transactions": [
        {
            "id": 31464,
            "order_id": 54627,
            "payment_provider": "STRIPE",
            "payment_provider_transaction_id": "pi_3PXoWvK29KDiBVld1n7ym4B0",
            "payment_method_id": 10630,
            "payment_provider_payment_method_id": "pm_1PXoWvK29KDiBVldLNqe04Oi",
            "payment_intent_client_secret": "pi_3PXoWvK29KDiBVld1n7ym4B0_secret_tB77zb3BoTCKigUe5R38hrCKS",
            "amount": 120000,
            "metadata": {
                "payment_intent_client_secret": "pi_3PXoWvK29KDiBVld1n7ym4B0_secret_tB77zb3BoTCKigUe5R38hrCKS",
                "payment_intent_id": "pi_3PXoWvK29KDiBVld1n7ym4B0"
            },
            "currency": "USD",
            "status": "CAPTURED",
            "errors": [],
            "date_created": "2024-07-01T18:00:45+0000",
            "date_last_modified": "2024-07-01T18:00:48+0000"
        }
    ],
    "sub_total": 0,
    "shipping_total": 0,
    "tax_total": 0,
    "total": 0,
    "app_order_id": "mario-test-1",
    "status": "COMPLETED",
    "is_guest": true,
    "date_created": "2024-06-28T20:31:56+0000",
    "date_last_modified": "2024-06-28T20:31:56+0000",
    "priced": true,
    "wallet_based_checkout": false,
    "currency": "USD",
    "channel": "MARKETPLACE",
    "currency_symbol": "$",
    "intent_based_checkout": true,
    "order_status": "COMPLETED",
    "order_id": 54609,
    "guest": true
}

    If there are any issues with submission, they will be returned to instead of the Order above. A new payment token will need to be sent with each Create Order request.

Was this page helpful?

Bypassing Payments through VioletOverview