Apply Payment Method

Apply a payment method to a cart given its cart_id.

You have the following options for payments:

1. Stripe.js V3 (recommended) - You can use this option by passing in the field intent_based_payment : true in the request body. Using this option will not automatically apply payment details. Please follow this guide to enable Stripe v3 Payments.

2. Raw Credit Card information (deprecation path) - You can use this option by passing in card_cvc, card_exp_month, card_exp_year, card_number and card_postal_code.

3. Tokenized credit card information (deprecation path) - You can use this by passing in a Tokenized card in the token field.

Apply Payment Method

post

Path parameters

cart_idinteger · int64Required

Query parameters

price_cartbooleanOptionalDefault: false

Header parameters

X-Violet-TokenstringRequired

X-Violet-App-SecretstringRequired

X-Violet-App-Idinteger · int32Required

Body

application/json

The payment method request for a cart. If the token is provided no card data is required.

tokenstringOptional

Payment Token generated on a specific payment provider. When a token is provided, payment_provider must also be specified in the request.

customer_idstringOptional

Unique identifier of the Customer in the payment provider that the payment method is associated to. When a customer_id is provided, payment_provider must also be specified in the request.

intent_based_capturebooleanOptional

Trigger payment intent based capture

payment_providerstringOptional

Payment provider that this payment method was created on, if any.

ip_v4stringOptional

IP address of the device from which this Payment Method originates.

typestring · enumOptional

Type of the payment method being passed in.

Possible values:

card_numberstringOptional

Number on the credit or debit card.

card_cvcinteger · int32Optional

CVC code on the credit or debit card.

card_exp_monthinteger · int32Optional

Expiration month of the credit or debit card.

card_exp_yearinteger · int32Optional

Expiration year of the credit or debit card.

card_postal_codestringOptional

Postal Code of the credit or debit card.

complete_checkoutbooleanOptional

Submit cart immediately after applying the payment method. Cannot be combined with intent_based_checkout.

app_order_idstringOptional

Map the order in Violet to an order record within your system.

Responses

200

success

application/json

Violet Order Entity

idinteger · int64Read-onlyOptional

ID of the Violet cart or order.

tokenstringRead-onlyOptionalDeprecated

An alternative UUID that can be used as an ID to reference the cart or order.

user_idinteger · int64OptionalDeprecated

ID of the User placing the order

app_idinteger · int32Optional

ID of the App responsible for the creation and submission of this Order.

developer_idinteger · int32Optional

ID of the Developer responsible for the creation and submission of this Order.

sub_totalinteger · int32Optional

The price of the Order in the base currency before discounts, shipping, duties, taxes, and tips. In Cents.

Default: 0

shipping_totalinteger · int32Optional

The sum of all shipping methods applied to the Order in the base currency. In Cents.

Default: 0

tax_totalinteger · int32Optional

The sum of all the taxes applied to the Order in the base currency. In Cents.

Default: 0

discount_totalinteger · int32Optional

The total discounts applied to the price of the Order in the base currency. In Cents.

Default: 0

totalinteger · int32Optional

The sum of all item prices, discounts, shipping, and taxes applied to the Order in the base currency. In Cents.

Default: 0

app_customer_idstring · nullableOptional

App Customer ID. This should be used to map the order to the ID of the customer in your application.

app_order_idstring · nullableOptional

App Order ID. This should be set to a unique identifier in your system. While not enforced unique in Violet's system, it is strongly recommended that unique values are used for each cart to help correlate identifiers between Violet's system and yours.

statusstring · enumRead-onlyOptional

Status of the Order

Possible values:

is_guestbooleanRead-onlyOptional

Order is Guest

Default: true

date_createdstring · date-timeRead-onlyOptional

Date of order creation

date_last_modifiedstring · date-timeRead-onlyOptional

Indicates when the order was last modified. This timestamp is updated only when a property on the Order entity itself changes. Modifications to related entities (e.g., Bags) will not update this timestamp unless the change also triggers an update to the Order entity.

date_submittedstring · date-time · max: 24 · nullableRead-onlyOptional

Date the Order was last submitted in Violet. This value is captured immediately after the Order is successfully validated and before the nested Bag(s) are submitted to the external commerce platforms.

pricedbooleanRead-onlyOptional

Is the cart priced

Default: false

wallet_based_checkoutbooleanOptional

Is this cart going to be placed through wallet-based checkout

Default: false

currencystringOptional

Base currency of cart

Default: USD

referral_idstring · nullableOptional

Optional value used to represent an identifier in your system. This value is not required to represent a referral. It can represent the ID of anything in your system and can be used to filter order lookup results. Max length of 128 characters.

currency_symbolstringOptional

Symbol representing the currency the Order operates in.

app_namestringOptional

Name of app that originated the order. Use the "extended" query param when looking up orders to include this value.

stripe_keystringOptional

Stripe publishable key. Use for tokenizing payment methods.

payment_intent_client_secretstringOptional

Payment intent client secret. Use for payment intent based payment capture and external captures

order_statusstring · enumOptionalPossible values:

guestbooleanOptional

intent_based_checkoutbooleanOptional

Boolean indicating if the cart/order will be payed using a payment intent.

order_idinteger · int64Optional

400

bad request

application/json

404

order not found

application/json

post

/checkout/cart/{cart_id}/payment

HTTPcURLJavaScriptPython

POST /v1/checkout/cart/{cart_id}/payment HTTP/1.1
Host: sandbox-api.violet.io
X-Violet-Token: text
X-Violet-App-Secret: text
X-Violet-App-Id: 1
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "token": "tok_amex"
}

{
  "id": 10000,
  "token": "fz8x7gksdjsy2p9fdlonw7k9svwjso4b",
  "user_id": 10000,
  "app_id": 10000,
  "developer_id": 10000,
  "customer": {
    "user_id": 10000,
    "first_name": "Super",
    "last_name": "Mario",
    "email": "[email protected]",
    "name": "Super Mario"
  },
  "bags": [
    {
      "id": 11111,
      "order_id": 10000,
      "merchant_id": 10000,
      "app_id": 10000,
      "status": "ACCEPTED",
      "fulfillment_status": "PROCESSING",
      "financial_status": "PAID",
      "skus": [
        {
          "id": 10000,
          "merchant_id": 10000,
          "app_id": 10000,
          "sku_id": 99999,
          "external_id": "1234567890",
          "name": "Nintendo Entertainment System",
          "brand": "Nintendo",
          "thumbnail": "https://res.cloudinary.com/violet/image/upload/c_thumb,w_200,g_face/v1729220594/product_media/2taesr1g7sciu8agrrtgaafi2dnzzmsv.jpg",
          "quantity": 2,
          "price": 9999,
          "weight": 1,
          "available": true,
          "status": "PROCESSING",
          "product_type": "PHYSICAL",
          "custom": false,
          "line_price": 19998
        }
      ],
      "shipping_method": {
        "carrier": "USPS",
        "shipping_method_id": "07d19139fc0f4558687c1900c696f071",
        "bag_id": 11111,
        "merchant_id": 10000,
        "label": "Priority Mail",
        "price": 644,
        "custom": false
      },
      "taxes": [
        {
          "order_id": 127021,
          "merchant_id": 10009,
          "state": "WA",
          "rate": 6.5,
          "amount": 1300,
          "description": "Washington State Tax"
        },
        {
          "order_id": 127021,
          "merchant_id": 10009,
          "state": "WA",
          "rate": 0,
          "amount": 0,
          "description": "King County Tax"
        },
        {
          "order_id": 127021,
          "merchant_id": 10009,
          "state": "WA",
          "rate": 3.85,
          "amount": 770,
          "description": "Seattle City Tax"
        }
      ],
      "sub_total": 19998,
      "shipping_total": 644,
      "tax_total": 2070,
      "discount_total": 0,
      "total": 22712,
      "taxes_included": false,
      "external_checkout": true,
      "commission_rate": 10,
      "date_created": "2017-06-15T01:01:01+0000",
      "date_last_modified": "2017-06-15T01:01:01+0000",
      "remorse_period_ends": "2017-06-15T01:01:01+0000",
      "currency": "USD",
      "external_currency": "USD",
      "channel": "APP",
      "platform": "SHOPIFY",
      "fulfillments": [],
      "discounts": [],
      "wallet_based_checkout": false,
      "bag_id": 22222,
      "bag_status": "IN_PROGRESS",
      "merchant_name": "Legacy Games"
    }
  ],
  "shipping_address": {
    "name": "Super Mario",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98121",
    "phone": "1234567890",
    "type": "SHIPPING",
    "address_1": "2815 Elliott Ave, Unit 100",
    "first_name": "Super",
    "last_name": "Mario"
  },
  "billing_address": {
    "name": "Super Mario",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98121",
    "phone": "1234567890",
    "type": "BILLING",
    "address_1": "2815 Elliott Ave, Unit 100",
    "first_name": "Super",
    "last_name": "Mario"
  },
  "payment_method": {
    "brand": "visa",
    "last_four": "4242",
    "exp_month": 12,
    "exp_year": 2025,
    "payment_method_id": 35236
  },
  "sub_total": 19998,
  "shipping_total": 644,
  "tax_total": 2070,
  "discount_total": 0,
  "total": 22712,
  "app_order_id": "00100100",
  "status": "COMPLETED",
  "is_guest": true,
  "date_created": "2017-06-15T01:01:01+0000",
  "date_last_modified": "2017-06-15T01:01:01+0000",
  "priced": true,
  "wallet_based_checkout": false,
  "currency": "USD",
  "channel": "APP",
  "currency_symbol": "$",
  "stripe_key": "pk_test_UHg8oLvg4rrDCbvtqfwTE8qd",
  "payment_intent_client_secret": "pi_vw8krrsvposl347c5l7x1nt5_secret_vbcw5t2bze37iptq430tmx7s",
  "intent_based_checkout": true,
  "guest": true,
  "order_id": 10000
}