Skip to main content

Create Stripe Payment Intent for a Cart

POST 
/v2/carts/:cartID/payments

The Cart Payment Intent feature enables the creation of a Stripe Payment Intent specifically tied to a shopping cart and its subsequent order. This allows Payment Intent users to track payment details from the cart stage and seamlessly maintain consistency in payment information throughout the order stage. Using these features, you can create Payment Intents for their carts, update Payment Intents with final cart details, and synchronize Payment Intents from Stripe to Commerce.

note
  • Typically, in Commerce, inventory is allocated at the time of payment initiation after an order is created. However, in the case of Cart Payment Intent, information about the payment is received only upon synchronizing the order from Stripe to Commerce. This may happen after the payment is completed. Therefore, there might be a delay between the payment made and allocation, increasing the chance of paying for items that are not in stock.
  • There are certain fields you can choose to set up when creating a payment intent. However, if you decide to update a payment intent, the available options may not be the same as those allowed while creating a payment intent. See updating a payment intent.

The following steps outline the workflow associated with the Payment Intent:

  1. Add items to cart.
  2. Create a Payment Intent for the cart. The Payment Intent is created in Stripe, reflecting the cart and transaction details, including currency, amounts, payment type, and any optional Stripe details. The Payment Intent ID is generated and linked to the cart.
  3. Update a Payment Intent. This step is optional but becomes necessary when there are changes in the cart details at the time of payment. It ensures the Payment Intent accurately reflects the current cart details when processing the payments on the front end.
  4. Checkout the cart. An unpaid order is created, and the Payment Intent ID is linked to the order.
  5. Confirm the order. This is important because after checkout, it is essential to confirm the Payment Intent and synchronize it with Commerce. This results in a corresponding transaction and change in order statuses in Commerce. Additionally, the Payment Intent ID is removed from the order once it is linked via the transaction.

Best Practices​

We recommend you follow these practices to maintain consistency and accuracy when using Cart Payment Intent.

  • After checkout, we recommend clearing the shopping cart. You can achieve this using a Delete a cart endpoint or Update a cart to remove the Payment Intent ID. This helps to avoid potential issues where subsequent checkouts for the same cart might unintentionally use the previous Stripe Payment Intent ID.
  • If it is not reasonable to clear the cart immediately after checkout due to several subsequent, duplicate checkouts to the same cart, ensure that you only synchronize the Payment Intent when finalizing the order. Each order confirmation is unaware of the others, and syncing Payment Intent IDs for each confirmation can lead to duplicate transactions in Commerce. In other words, if you synchronize Payment Intents for earlier versions of a repeated checkout, you'll end up with multiple orders from the same cart, each having transactions linked to the same Payment Intent.
  • To pay the entire amount at once, use the Update Cart Payment Intent endpoint to update the Stripe Payment Intent with the final cart details when preparing to take the payment. Doing so, ensures that the Payment Intent accurately reflects the current cart details when processing payments on the front end. We do not recommend calling the Update Cart Payment Intent for each individual change in the cart, as this can lead to more requests and may slow down the front-end performance.

Request​

Path Parameters

    cartID stringrequired

    The universally unique identifier of the cart for which you want to create a payment intent.

Body

    gateway stringrequired

    Possible values: [elastic_path_payments_stripe]

    Specifies the gateway. You must use elastic_path_payments_stripe.

    method stringrequired

    Possible values: [authorize, purchase, purchase_setup, authorize_setup]

    Specifies the transaction method, such as purchase or authorize.

    amount number

    The amount to be paid for the transaction.

    options object
    receipt_email string

    Provides the email address to which you want to send the Stripe receipts for the transactions within the store. This feature is available only in the live mode.

    automatic_payment_methods object

    Parent object determining whether to use Stripe's automatic_payment_methods setting.

    enabled boolean

    When set to true, it displays all enabled payment methods from the Stripe dashboard. When set to false, the Stripe default, which is card, is used.

    payment_method_types string[]

    Specifies the Stripe payment method types configured for the store. See Stripe Documentation.

    payment string

    Specifies the Stripe token or source.

Responses​

Payment Intent created successfully.

Schema
    id string

    The unique identifier for the cart. Use SDK or create it yourself.

    type string

    The type of object being returned.

    name string

    The name of this cart.

    description string

    A description of the cart.

    discount_settings object
    custom_discounts_enabled boolean

    This parameter enables custom discounts for a cart. When set to true, Elastic Path promotions will not be applied to the new carts. Default is set from cart discount settings for the store. See Cart Settings.

    use_rule_promotions boolean

    When set to true, this parameter allows the cart to use rule promotions.

    payment_intent_id string

    Stripe-assigned unique identifier for the linked Payment Intent

    links object
    self string

    A link to that specific resource.

    meta object
    display_price object
    with_tax object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    without_tax object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    tax object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    discount object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    without_discount object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    shipping object
    amount number

    The raw total of this cart.

    currency string

    The currency set for this cart.

    formatted string

    The tax inclusive formatted total based on the currency.

    timestamps object
    created_at string

    The date this was created.

    updated_at

    The date this was last updated.

    relationships object
    customers object
    data object
    type string

    The type of related object.

    id uuid

    The ID of the customer.

    items object
    data object
    type string

    The type of related object.

    id uuid

    The unique identifier for the cart item

Loading...