Submitting a Direct Order with a Payment Method
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.
Definitions and Concepts
Prism Pay
Prism Pay is a payment orchestration service that allows Channels and their merchants to use Violet for processing payments. With Prism Pay, Violet handles tasks like charging shoppers, calculating distributions, transferring funds, and reporting payouts for processed orders. For example, a Channel can use Prism Pay instead of building their own payments stack.
Cart
A cart is a virtual collection of items that a shopper intends to purchase. It includes details such as the selected SKUs, their quantities, and the estimated total cost including shipping, taxes, and discounts.
Order
An order is a completed request for the purchase of items listed in the cart. It includes detailed information about the shopper, payment method, shipping and billing addresses, and the selected SKUs. I
Offer
An offer represents a purchasable product available on Violet through integrated Merchants. Offers are often called Products in other e-commerce platforms and is the parent entity for all of the nested SKUs (Stock Keeping Units) associated with that offer.
SKU (Stock Keeping Unit)
A SKU is a unique identifier assigned to each product or service available for sale. It helps track inventory and manage product listings. When creating an Order, SKU identifiers need to be passed in as a part of the request.
Payment Method
A payment method is the way a shopper chooses to pay for their order. For this API, only single use Stripe Tokens can be passed in as payment methods.
Stripe Token
A Stripe Token is a secure, single-use representation of a shopper’s payment information. It is generated by Stripe and used to facilitate payments without exposing sensitive card details.
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:
- First Name
- Last Name
- 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>" ] } ] }
Creating a Stripe Token
If you are not using Prism Pay, you can ignore this step. When creating an Order in the next step, simply leave out the payment_method in the request.
Violet currently only supports accepting Stripe Tokens when using the Direct Order Submission Checkout flow. You cannot use the following flow in Standard Checkout.
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.
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:
- First Name
- Last Name
- Shipping Address
- 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?