Elastic Path Payments API

openapi: 3.2.0
info:
  title: Carts, Checkout, Orders Introduction Payments API
  description: 'A cart contains a list of the products that a shopper adds to the cart while browsing your catalog. In the context of a cart, a selected product is called a cart item.


    A cart item identifies the product, the product price, the quantity selected, and the total price for the quantity selected. The cart displays a running total of the cost for the selected products plus the calculated tax.


    You can allow your shoppers to add custom text to a product when adding an item to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized. See [Add product to cart](/docs/api/carts/manage-carts#add-product-to-cart).


    After a shopper checks out, the cart is converted to an order, and you can manually delete the cart. If you don''t delete the cart, it is purged automatically after seven days.


    The preview cart feature allows you to set a future date for your shopping cart and view the promotions that will be available during that time period. This feature enables you to validate your promotion settings and observe how they will be applied in the cart. See [Create a Preview Cart](/docs/api/carts/create-a-cart#preview-cart).


    The following diagram shows a typical cart workflow:


    ![Shows a cart workflow, starting from adding the first item to a cart, through cart creation and checkout](/assets/cart-workflow.png)


    ### Multiple Carts


    Buyers often make purchases based on jobs that they need to perform or outcomes they need to achieve and therefore require more than one shopping cart. For example, a corporate buyer places orders for multiple locations. Each location has a different frequency of ordering and require different products. The buyer can create one cart per location, fill the carts, and then check out the carts quickly. Similarly, shoppers can also create multiple carts for the ease of managing various shopping experiences, such as birthdays or holidays.


    Each cart is discrete and separate. Any updates or changes to one cart has no effect on the other carts. A cart persists, that is, it stays with the buyer or shopper even after they use the cart in a checkout. Carts remain available after a checkout.

    '
  contact:
    name: Elastic Path
    url: https://elasticpath.com
  version: 26.0313.7324347
  x-version-timestamp: 2026-03-13 21:22:42+00:00
  license:
    name: MIT
    url: assets/LICENSE
servers:
- url: https://useast.api.elasticpath.com
  description: US East Production Server
  variables: {}
- url: https://euwest.api.elasticpath.com
  description: EU West Production Server
  variables: {}
security:
- bearerAuth: []
tags:
- name: Payments
  description: 'When you [checkout](/docs/api/carts/checkout) a [cart](/docs/api/carts/cart-management), an unpaid [order](/docs/api/carts/orders) is returned. You can process the payment for the order though a payment gateway.


    :::note


    - You need to configure and enable a payment gateway before you can accept payments for orders.

    - Configure your store to use [Manual Gateway](/docs/api/payments/update-manual-gateway) to process payments if the order total is zero or the payment is through non-supported payment providers.

    - There are a number of actions that happen to your inventory when checking out and paying for an order. For more information, see [Inventory](/docs/api/pxm/inventory/inventories-introduction).

    - We recommend to wait until the payment confirmation process is fully completed before proceeding with any additional updates to the order. Making simultaneous updates to the same entity immediately after payment confirmation can lead to a race condition. To learn more information on handling parallel calls to API objects, see [Parallel Calls to API Objects](/guides/Getting-Started/api-contract#parallel-calls-to-api-objects).


    :::


    ### Payment Methods


    Depending on the chosen gateway, you may or may not have access to capture funds immediately or authorize for later payment.


    To make a partial payment in Postman through any payment gateway, specify the desired payment amount in the amount field within the request body. To learn about Split Payments, see the [Split Payments](/docs/api/payments/payment-gateways-introduction#split-payments) section.


    #### Purchase


    The simplest method is purchase. The gateway attempts to charge the customer immediately, and the result of the attempt is returned.


    You can partially pay funds using purchase method. The gateway attempts to charge the customer immediately, and the payment status for an order shows `partially_paid`.


    When you Get an order, you can see the following fields in the `meta` object:


    - `balance_owing`: Specifies the outstanding funds required to complete an order. It considers all complete or pending transactions, including authorized, paid, and captured transactions. (`balance_owing` = order total - `authorized` amount - `paid` amount).

    - `paid`: Specifies the total amount of purchased or captured transactions.

    - `authorized`: Specifies the total amount of completed or pending authorized transactions for an order.


    #### Authorize


    You can `authorize` a payment so funds can later be captured when an item is dispatched or restocked.


    You can partially pay for an order using `authorize` payment method so that the order is `partially_authorized`. The transaction must be complete for the order status to be `partially_authorized`.


    For more information about order and payment statuses for split payments, see [Split Payments](/docs/api/payments/payment-gateways-introduction#split-payments).


    #### Capture


    After authorizing a transaction, you have to capture the authorized funds.


    :::note


    We recommend capturing payments several hours to days after the authorization to mitigate risks of fraud and chargebacks. When you sell digital goods that are delivered immediately, we recommend using a single purchase call instead of separate authorize and capture calls.


    :::


    After the payment is `partially_authorized`, you must `capture` the authorized transaction later. Once you capture the authorized transactions, the order payment status will change to `partially_paid`.


    #### Refunds


    You can use either the Refund through Composable Commerce or use the Mark as Refunded capability, or a combination of both capabilities.


    For more information about refund for split payments, see [Refund a Payment](/docs/api/carts/refund-a-transaction).


    #### Refund through Composable Commerce


    You can start a full or partial refund to a supported payment provider directly from Commerce Manager or the API. When you start the refund process, the refund request is sent to the payment gateway. You no longer have to log on to your payment gateway''s console to process the refund.


    When you process a refund, use the refund endpoint to pass the refund amount. If you don''t pass an amount, the refund is processed as Mark as refunded. For more information, see the Mark as Refunded section.


    Each time a partial refund is triggered, the transaction.updated event is generated and updated with refunded.amount. The `order.updated` event is also triggered. The `order.refunded` event generates when the full amount is refunded.



    #### Mark as Refunded


    You can use your payment gateway''s console to process a refund. Process the refund first in the payment gateway and then use the **Mark as Refunded** capability in Composable Commerce to complete the process.


    When an order is **Marked as refunded**, the payment status `order.payment.status` is set to `refunded`. In this case, the `order.updated`, `transaction.updated` and `order.refunded` events are generated.

    '
paths:
  /v2/carts/{cartID}/payments:
    parameters: []
    post:
      tags:
      - Payments
      summary: Create Stripe Payment Intent for a Cart
      description: '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](https://stripe.com/docs/api/payment_intents/create). 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](https://stripe.com/docs/api/payment_intents/update).


        :::


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


        1. [Add items to cart](/docs/api/carts/manage-carts#add-custom-item-to-cart).

        1. [Create a Payment Intent for the cart](/docs/api/carts/create-cart-payment-intent). 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.

        1. [Update a Payment Intent](/docs/carts-orders/update-cart-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.

        1. [Checkout the cart](/docs/api/carts/checkout). An unpaid order is created, and the Payment Intent ID is linked to the order.

        1. [Confirm the order](/docs/carts-orders/confirm-an-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](/docs/api/carts/delete-a-cart) endpoint or [Update a cart](/docs/api/carts/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](/docs/carts-orders/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](/docs/carts-orders/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.

        '
      operationId: createCartPaymentIntent
      parameters:
      - name: cartID
        in: path
        required: true
        style: simple
        schema:
          type: string
        description: The universally unique identifier of the cart for which you want to create a payment intent.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ElasticPathPaymentsPoweredByStripePayment'
            examples:
              Create Stripe Payment Intent for a Cart:
                value:
                  data:
                    gateway: elastic_path_payments_stripe
                    method: purchase
                    options:
                      automatic_payment_methods:
                        enabled: true
                      receipt_email: john@example.com
              Create Stripe Payment Intent for a Cart Using Specific Payment Methods:
                value:
                  data:
                    gateway: elastic_path_payments_stripe
                    method: purchase
                    payment_method_types:
                    - affirm
                    - card
                    - link
                    options:
                      receipt_email: john@example.com
      responses:
        '201':
          description: Payment Intent created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartEntityResponse'
      deprecated: false
  /v2/orders/{orderID}/payments:
    parameters: []
    post:
      tags:
      - Payments
      summary: Payments
      description: 'Depending on the payment gateway, you may have access to different transaction types such as capturing funds immediately or authorizing them for later. For more information, see [Payments](/docs/api/carts/payments).


        The following types of payment methods are available depending on the payment gateway:


        - `purchase`: This is the simplest method. The gateway attempts to charge the customer immediately.

        - `authorize`: This method authorizes a payment so that funds can be captured later, for example, when an item is dispatched or restocked.

        - `purchase_setup`: This method prepares the system for a purchase by verifying payment details without actually charging the customer. For example, a customer adds items to their cart and proceeds to checkout. Before finalizing the purchase, the system runs `purchase_setup` to confirm all payment details, but no funds are transferred until the customer confirms the order.

        - `authorize_setup`: This method prepares the system for an authorization-only transaction. This process holds the necessary funds but does not transfer them, ensuring that the customer has sufficient balance for the transaction. It sets up the conditions for a future capture of the authorized funds. For example, a customer places a pre-order for a product that will ship in two weeks. The merchant uses `authorize_setup` to prepare for the payment authorization. This holds the customer''s funds to ensure they can cover the purchase but waits to capture the payment until the product ships. This ensures that payment is secured but not collected prematurely.


        :::note


        Split payments can be performed using any methods for any gateway.


        - You can partially pay funds using `purchase` method. The gateway attempts to charge the customer immediately, and the payment status for an order will show `partially_paid`

        - You can partially pay for an order using `authorize` method where the order will be marked as `partially_authorized`. The transaction must be completed for the order status to be `partially_authorized`.

        - A `purchase_setup` method allows verification of payment details for partial payments without transferring funds until the customer confirms the full order.

        - An `authorize_setup` method can be used to hold a partial amount of the total funds, ensuring the customer has enough balance for a future capture.

        Until a payment is made neither `purchase_setup` nor `authorize_setup` affects the payment statuses, and the order remains unpaid. For more information about order and payment statuses for split payments, see [Split payments](/docs/api/payments/payment-gateways-introduction#split-payments).


        :::

        '
      operationId: paymentSetup
      parameters:
      - name: orderID
        in: path
        description: The Universally Unique Identifier (UUID) of the order you want to pay for.
        required: true
        style: simple
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/PaymentsRequest'
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionEntityResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
              examples:
                default:
                  summary: Required field missing
                  value:
                    errors:
                    - detail: Request could not be processed
                      status: '400'
                      title: Bad Request
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
      deprecated: false
  /v2/orders/{orderID}/transactions/{transactionID}/confirm:
    parameters: []
    post:
      tags:
      - Payments
      summary: Confirm Payment
      description: 'Confirm Payment serves as a mechanism to synchronize transaction information from the third-party payment provider back to our system. This ensures that Composable Commerce accurately reflects the values from the payment provider.


        ### Handling 3D Secure Validations for Stripe Payments


        For Stripe Payments requiring 3D Secure validation, the transaction response will include the `client_parameters` object, which provides credentials to support validation of these payment requests on the payment provider''s side. We recommend using the Stripe''s client libraries to manage these 3D Secure validations. Once the validation succeeds, proceed with a confirmation request to sync the validated transaction into Composable Commerce and continue with the payment process.

        '
      operationId: confirmPayment
      parameters:
      - name: orderID
        in: path
        description: The unique identifier of the order.
        required: true
        style: simple
        schema:
          type: string
      - name: transactionID
        in: path
        description: The unique identifier of the transaction.
        required: true
        style: simple
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/OrdersTransactionsConfirmRequest'
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionEntityResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
              examples:
                default:
                  summary: Required field missing
                  value:
                    errors:
                    - detail: Request could not be processed
                      status: '400'
                      title: Bad Request
      deprecated: false
  /v2/orders/{orderID}/transactions/{transactionID}/capture:
    parameters: []
    post:
      tags:
      - Payments
      summary: Capture a Transaction
      description: Use this endpoint to capture a previously authorized payment. In this step, you can also pass in a custom reference, such as the payment reference from your chosen gateway.
      operationId: captureATransaction
      parameters:
      - name: orderID
        in: path
        description: The UUID of the order.
        required: true
        style: simple
        schema:
          type: string
      - name: transactionID
        in: path
        description: The UUID of the transaction to capture.
        required: true
        style: simple
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/OrdersTransactionsCaptureRequest'
        required: false
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionEntityResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
              examples:
                default:
                  summary: Required field missing
                  value:
                    errors:
                    - detail: Request could not be processed
                      status: '400'
                      title: Bad Request
      deprecated: false
  /v2/orders/{orderID}/transactions/{transactionID}/refund:
    parameters: []
    post:
      tags:
      - Payments
      summary: Refund a Transaction
      description: 'There are two ways to refund; through your payment gateway and mark it refunded in Commerce Manager, or directly through Commerce Manager or API.


        * Mark as Refunded: You can manually mark a transaction as refunded. Before you can mark the order as refunded, you need to handle the actual refund on your side with your payment provider. Mark as Refunded is a full refund made to the transaction.

        * Refund through Composable Commerce: You can process a full or partial refund to a supported payment provider directly from Commerce Manager or API by providing the refund amount. When you start the refund process, the request is directly sent to the payment gateway.


        :::caution


        If you use manual gateway for partial or full refund, you need to handle the actual refund on your side with your payment provider.


        :::

        '
      operationId: refundATransaction
      parameters:
      - name: orderID
        in: path
        description: The UUID of the order.
        required: true
        style: simple
        schema:
          type: string
      - name: transactionID
        in: path
        description: The UUID of the transaction you want to refund.
        required: true
        style: simple
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/OrdersTransactionsRefundRequest'
        required: false
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionEntityResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
                examples:
                  default:
                    summary: Validation error
                    value: "{\n  \"errors\": [\n    {\n      \"detail\": \"Transaction cannot be refunded in its current state\",\n      \"status\": \"422\",\n      \"title\": \"Unprocessable Entity\"\n    }\n  ]\n}\n"
      deprecated: false
  /v2/orders/{orderID}/transactions:
    parameters: []
    get:
      tags:
      - Payments
      summary: Get Order Transactions
      description: Get order transactions
      operationId: getOrderTransactions
      parameters:
      - name: orderID
        in: path
        description: The unique identifier of the order.
        required: true
        style: simple
        schema:
          type: string
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
                examples:
                  default:
                    summary: Required field missing
                    value: "{\n  \"errors\": [\n    {\n      \"detail\": \"Request could not be processed\",\n      \"status\": \"400\",\n      \"title\": \"Bad Request\"\n    }\n  ]\n}\n"
      deprecated: false
  /v2/orders/{orderID}/transactions/{transactionID}:
    parameters: []
    get:
      tags:
      - Payments
      summary: Get a Transaction
      description: Retrieves a transaction
      operationId: getATransaction
      parameters:
      - name: orderID
        in: path
        description: The unique identifier of the order that you require transactions for.
        required: true
        style: simple
        schema:
          type: string
      - name: transactionID
        in: path
        description: The unique identifier of the transaction.
        required: true
        style: simple
        schema:
          type: string
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Response.Data'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/TransactionResponse'
      deprecated: false
  /v2/orders/{orderID}/transactions/{transactionID}/cancel:
    parameters: []
    post:
      tags:
      - Payments
      summary: Cancel a Transaction
      description: 'Use this endpoint to cancel or void a pending or authorized transaction. The transaction can be canceled or voided when it is in `pending` and `completed` statuses.


        :::caution


        This endpoint works only for Stripe and PayPal and does not work for manual gateway.


        :::

        '
      operationId: cancelATransaction
      parameters:
      - name: orderID
        in: path
        description: The unique identifier of the order.
        required: true
        style: simple
        schema:
          type: string
      - name: transactionID
        in: path
        description: The unique identifier of the transaction to be canceled or voided.
        required: true
        style: simple
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/OrdersTransactionsCancelRequest'
        required: false
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/TransactionEntityResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
      deprecated: false
components:
  schemas:
    BaseCartResponse:
      title: BaseCartResponse
      type: object
      properties:
        id:
          description: The unique identifier for the cart. Use SDK or create it yourself.
          type: string
        name:
          description: The name of this cart.
          type: string
          examples:
          - cart name
        description:
          description: A description of the cart.
          type: string
          examples:
          - cart description
        contact:
          $ref: '#/components/schemas/CartContact'
        discount_settings:
          $ref: '#/components/schemas/DiscountSettings'
        inventory_settings:
          $ref: '#/components/schemas/InventorySettings'
        item_settings:
          $ref: '#/components/schemas/ItemSettings'
        payment_intent_id:
          description: Stripe-assigned unique identifier for the linked Payment Intent
          type: string
        custom_attributes:
          $ref: '#/components/schemas/CustomAttributes'
        snapshot_date:
          description: The snapshot date for the cart.
          type: string
          format: date-time
        links:
          type: object
          properties:
            self:
              description: A link to that specific resource.
              type: string
          examples:
          - https://useast.api.elasticpath.com/v2/carts/1
        meta:
          type: object
          properties:
            display_price:
              type: object
              properties:
                with_tax:
                  $ref: '#/components/schemas/FormattedPriceData'
                without_tax:
                  $ref: '#/components/schemas/FormattedPriceData'
                tax:
                  $ref: '#/components/schemas/FormattedPriceData'
                discount:
                  $ref: '#/components/schemas/FormattedPriceData'
                without_discount:
                  $ref: '#/components/schemas/FormattedPriceData'
                shipping:
                  $ref: '#/components/schemas/FormattedPriceData'
                shipping_discount:
                  $ref: '#/components/schemas/FormattedPriceData'
            timestamps:
              $ref: '#/components/schemas/CartTimestamps'
            promotion_suggestions:
              description: Array of promotion suggestions
              type: array
              items:
                type: object
                properties:
                  bundle:
                    description: Bundle configuration with promotion targets
                    type: array
                    items:
                      type: object
                      properties:
                        auto_add_free_gift:
                          description: Whether to automatically add free gift
                          type: boolean
                        cart_item_id:
                          description: Cart item ID for the target
                          type: string
                        quantity:
                          description: Quantity for the promotion
                          type: integer
                        targets:
                          description: Array of target SKUs
                          type: array
                          items:
                            type: string
                      additionalProperties: true
                  code:
                    type: string
                  info:
                    type: string
                  message:
                    type: string
                  promotion_id:
                    type: string
        relationships:
          type: object
          prop

# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-payments-api-openapi.yml