openapi: 3.1.0 info: version: 25.1126.6886238 x-version-timestamp: 2025-11-26 19:10:23+00:00 title: Addresses Introduction Account Addresses Payments API description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour. You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token. ' contact: name: Elastic Path url: https://www.elasticpath.com email: support@elasticpath.com license: url: https://elasticpath.dev name: MIT servers: - url: https://useast.api.elasticpath.com description: US East - url: https://euwest.api.elasticpath.com description: EU West security: - BearerToken: [] 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: TransactionListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/TransactionResponse' required: - data CustomDiscountResponse: title: CustomDiscountResponse type: object properties: type: description: Specifies the type of the resource. Always `custom_discount`. type: string const: custom_discount id: description: Specifies the UUID of the custom discount. type: string format: uuid examples: - 662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9 external_id: description: Specifies an external id for the custom discount. type: string examples: - custom-discount-external-id discount_engine: description: 'Specifies from where the custom discount is applied. ' type: string examples: - Custom Discount Engine amount: description: The amount of the custom discount. $ref: '#/components/schemas/FormattedPriceData' description: description: Specifies a description for the custom discount. type: string examples: - Custom discount description discount_code: description: Specifies the discount code used for the custom discount. type: string examples: - cart-custom-promo-code relationships: description: Relationships to other resources like cart items type: object properties: item: type: object properties: data: type: object properties: id: type: string format: uuid description: The cart item ID this discount is related to type: type: string enum: - cart_item - custom_item CartResponse: title: CartResponse allOf: - $ref: '#/components/schemas/BaseCartResponse' - type: object properties: type: description: The type of object being returned. type: string const: cart Data.PaymentObject: oneOf: - $ref: '#/components/schemas/Data.AdyenPayment' - $ref: '#/components/schemas/Data.AuthorizeNetPayment' - $ref: '#/components/schemas/Data.BraintreePayment' - $ref: '#/components/schemas/Data.CardConnectPayment' - $ref: '#/components/schemas/Data.CyberSourcePayment' - $ref: '#/components/schemas/ElasticPathPaymentsPoweredByStripePayment' - $ref: '#/components/schemas/Data.ManualPayment' - $ref: '#/components/schemas/Data.PayPalExpressCheckoutPayment' - $ref: '#/components/schemas/Data.StripePayment' - $ref: '#/components/schemas/Data.StripePaymentIntentsPayment' FormattedPriceData: title: FormattedPriceData type: object properties: amount: description: The raw total. type: number examples: - 10000 currency: description: The currency set for this amount. type: string examples: - USD formatted: description: The formatted total based on the amount and currency. type: string examples: - $10.00 Response.ErrorItem: type: object required: - status - title properties: title: type: string description: A brief summary of the error. examples: - Bad Request status: type: - string - integer description: The HTTP response code of the error. examples: - '400' detail: type: string description: Optional additional detail about the error. examples: - The field 'name' is required source: type: string description: The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity'). meta: type: object description: Additional metadata associated with the error. May include arbitrary keys. properties: id: type: string description: The resource id associated with the error ids: type: array items: type: string description: The resource ids associated with the error item_ids: type: array items: type: string description: The cart_item ids associated with the error shipping_group_id: type: string description: The shipping group id associated with the error shipping_group_ids: type: array items: type: string description: The shipping group ids associated with the error cart_id: type: string description: The cart id associated with the error code: type: string description: The code associated with the error. order_id: type: string description: The order id associated with the error. sku: type: string description: The SKU associated with the error. email: type: string format: email description: The email address associated with the error. component_product_id: type: string format: uuid description: The component product ID associated with the error. error-meta-key: type: string description: Custom error metadata key used for additional error context (e.g., in payment rejections). value: description: The value associated with the error. oneOf: - type: string - type: integer - type: boolean - type: object additionalProperties: true - type: array Timestamps: type: object properties: created_at: description: The date this was created. type: string updated_at: description: The date this was last updated. type: string ElasticPathPaymentsPoweredByStripePayment: title: Elastic Path Payments Powered By Stripe type: object properties: data: allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the gateway. You must use `elastic_path_payments_stripe`. type: string const: elastic_path_payments_stripe options: type: object properties: receipt_email: description: 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. type: string automatic_payment_methods: type: object description: Parent object determining whether to use Stripe's `automatic_payment_methods` setting. properties: enabled: type: boolean description: 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: type: array items: type: string description: Specifies the Stripe payment method types configured for the store. See [Stripe Documentation](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-payment_method_types). examples: - - card payment: description: Specifies the Stripe token or source. type: string Data.StripePaymentIntentsPayment: title: Data.StripePaymentIntentsPayment required: - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the type of payment gateway. You must use `stripe_payment_intents`. type: string const: stripe_payment_intents options: type: object properties: receipt_email: description: 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. type: string payment: description: Specifies the Stripe token or source. type: string CondensedPromotionResponse: title: CondensedPromotionResponse type: object properties: type: description: Specifies the type of the resource. Always `promotion`. type: string const: promotion examples: - promotion id: description: Specifies the UUID of the promotion. type: string format: uuid readOnly: true examples: - 662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9 name: description: The name of the promotion. type: string examples: - Summer Sale description: description: The description of the promotion. type: string examples: - Get 20% off all summer items automatic: description: Whether the promotion is applied automatically. type: boolean examples: - true promotion_type: description: The type of promotion (for v1 promotions). type: string examples: - discount promotion_source: description: The source of the promotion (for rule promotions). type: string examples: - rule-promotion start: description: The start date and time of the promotion. type: string format: date-time examples: - '2024-06-01T00:00:00Z' end: description: The end date and time of the promotion. type: string format: date-time examples: - '2024-08-31T23:59:59Z' TransactionResponse: title: TransactionResponse type: object properties: id: description: The ID of the transaction. type: string format: uuid readOnly: true reference: description: The payment gateway reference. type: string examples: - manual name: description: A custom name associated with the payment method. type: string examples: - payment method name custom_reference: description: A reference associated with the payment method. This might include loyalty points or gift card identifiers. We recommend you not to include personal information in this field. type: string examples: - custom reference gateway: description: The name of the payment gateway used. type: string enum: - adyen - authorize_net - braintree - card_connect - cyber_source - elastic_path_payments_stripe - manual - paypal_express_checkout - stripe - stripe_payment_intents - stripe_platform_account amount: description: The amount for this transaction. type: number examples: - 10000 refunded_amount: description: The refunded amount. type: number examples: - 0 currency: description: The transaction currency. type: string examples: - USD transaction_type: description: The type of transaction, such as `purchase`, `capture`, `authorize` or `refund`. type: string enum: - purchase - authorize - capture - refund type: description: The type of object being returned. type: string status: description: The status provided by the gateway for this transaction, such as `complete` or `failed`. type: string examples: - complete payment_details: description: Payment gateway specific details. type: object properties: detailed_status: description: Detailed status from the payment gateway. type: string failure_details: description: Non-PII payment failure details from the gateway. Only present on failed transactions where the gateway provided structured failure information. $ref: '#/components/schemas/FailureDetails' payment_intent: description: Payment intent details. type: object additionalProperties: true capture_mechanism: description: The mechanism used for capturing the transaction. type: string enum: - automatic - manual refund_mechanism: description: The mechanism used for refunding the transaction. type: string enum: - automatic - manual client_parameters: description: Client-specific parameters for payment processing. type: object properties: redirect_url: description: URL to redirect the client after payment. type: string secret: description: Client secret for payment processing. type: string token: description: Client token for payment processing. type: string next_actions: description: Array of next actions for the transaction. type: array items: type: string relationships: type: object properties: order: type: object properties: data: type: object properties: type: description: Represents the type of the object being returned. It is always `order`. type: string examples: - order id: description: The ID of the order. type: string format: uuid examples: - 5601a4b1-9d13-42d3-8fb7-03b35169d1b6 meta: type: object properties: display_price: $ref: '#/components/schemas/FormattedPriceData' display_refunded_amount: type: object properties: total: $ref: '#/components/schemas/FormattedPriceData' timestamps: $ref: '#/components/schemas/Timestamps' CartContact: title: CartContact type: object properties: email: description: The email address attached to a cart. type: string format: email examples: - tester@email.com 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 properties: customers: anyOf: - $ref: '#/components/schemas/RelationshipArray' - type: object maxProperties: 0 items: anyOf: - $ref: '#/components/schemas/RelationshipArray' - type: object properties: data: oneOf: - type: 'null' - type: array items: type: object properties: id: type: string type: type: string required: - data accounts: anyOf: - $ref: '#/components/schemas/RelationshipArray' - type: object maxProperties: 0 custom_discounts: $ref: '#/components/schemas/RelationshipArray' promotions: $ref: '#/components/schemas/RelationshipArray' CartEntityResponse: type: object properties: data: $ref: '#/components/schemas/CartResponse' included: type: object description: Related objects that are included in the response. properties: custom_discounts: type: array items: $ref: '#/components/schemas/CustomDiscountResponse' promotions: type: array items: $ref: '#/components/schemas/CondensedPromotionResponse' meta: type: object description: Additional metadata for the cart response. properties: payment_intent: type: object description: Payment intent details with nested structure including status and other Stripe payment intent fields additionalProperties: true errors: type: array description: Array of error objects, if any errors occurred. items: $ref: '#/components/schemas/Response.ErrorItem' RelationshipItem: title: RelationshipItem description: Relationship data entry required: - type - id type: object properties: type: description: The type of related resource. type: string id: description: The ID of the related resource. type: string format: uuid CartTimestamps: type: object properties: created_at: description: The date this was created. type: string updated_at: description: The date this was last updated. type: string expires_at: description: The date this expires. type: string Data.CyberSourcePayment: title: Data.CyberSourcePayment required: - payment - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the gateway. You must use `cyber_source`. type: string const: cyber_source payment: description: The CyberSource token. type: string Data.CardConnectPayment: title: Data.CardConnectPayment required: - payment - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the gateway. You must use `card_connect`. type: string const: card_connect payment: description: Enter account_id, profile_id from CardPointe API. For example, 1|16178397535388255208. type: string FailureDetails: title: FailureDetails description: Non-PII payment failure information from the payment gateway. Only present on failed transactions where the gateway provided structured failure details. type: object properties: code: description: Machine-readable failure or error code from the payment gateway. type: string examples: - '2' reason: description: Human-readable failure reason or error message from the payment gateway. type: string examples: - This transaction has been declined. OrdersTransactionsCancelRequest: title: OrdersTransactionsCancelRequest type: object properties: data: type: object properties: options: type: object reason: description: Specifies the reason for canceling the transaction. The reason may include `duplicate`, `fraudulent`, `requested_by_customer`, or `abandoned`. type: string examples: - requested_by_customer Data.BasePayments: title: Data.BasePayments type: object required: - gateway - method properties: gateway: type: string enum: - adyen - authorize_net - braintree - card_connect - cyber_source - elastic_path_payments_stripe - manual - paypal_express_checkout - stripe - stripe_payment_intents method: description: Specifies the transaction method, such as `purchase` or `authorize`. type: string enum: - authorize - purchase - purchase_setup - authorize_setup amount: description: The amount to be paid for the transaction. type: number examples: - 10000 OrdersTransactionsRefundRequest: title: OrdersTransactionsRefundRequest type: object properties: data: type: object properties: amount: description: The amount value to be refunded. If this field is not provided, it will be considered as manual refund (Mark as Refunded) and the refund process must be manually handled via payment provider. If the amount value is same as payment value, then it will be treated as a full refund and sent to the payment provider to process refund automatically. type: number examples: - 1000 options: type: object properties: note: description: Provides comments about the refund. It is used by PayPal Express. type: string OrdersTransactionsConfirmRequest: title: OrdersTransactionsConfirmRequest type: object properties: data: type: object Data.BraintreePayment: title: Data.BraintreePayment required: - payment - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the gateway. You must use `braintree`. type: string const: braintree payment: description: The Braintree Customer ID that you want to bill. type: string Data.AuthorizeNetPayment: title: Data.AuthorizeNetPayment required: - payment - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the gateway. You must use `authorize_net`. type: string const: authorize_net options: type: object properties: customer_payment_profile_id: description: The Authorize.net customer payment profile ID. type: string payment: description: The Authorize.net customer profile ID. type: string Data.AdyenPayment: title: Data.AdyenPayment required: - payment - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the gateway. You must use `adyen`. type: string const: adyen options: type: object properties: shopper_reference: description: The shopper reference token associated with the saved payment method. type: string recurring_processing_model: description: Enter CardOnFile for a one-time purchase. type: string payment: description: The Adyen recurringDetailReference payment method identifier. type: string DiscountSettings: title: DiscountSettings type: object properties: custom_discounts_enabled: description: 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](/docs/api/carts/put-v-2-settings-cart). type: boolean examples: - false use_rule_promotions: description: When set to true, this parameter allows the cart to use rule promotions. type: boolean examples: - false OrdersTransactionsCaptureRequest: title: OrdersTransactionsCaptureRequest type: object properties: data: type: object properties: options: type: object properties: soft_descriptor: type: string note_to_payer: type: string TransactionEntityResponse: type: object properties: data: type: object $ref: '#/components/schemas/TransactionResponse' required: - data Response.ErrorResponse: type: object required: - errors properties: errors: type: array items: $ref: '#/components/schemas/Response.ErrorItem' PaymentsRequest: title: PaymentsRequest type: object properties: data: $ref: '#/components/schemas/Data.PaymentObject' Data.PayPalExpressCheckoutPayment: title: Data.PayPalExpressCheckoutPayment required: - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the type of payment gateway. You must use `paypal_express_checkout`. type: string const: paypal_express_checkout options: type: object properties: description: description: The description for the payment. type: string soft_descriptor: description: The descriptor appended to PayPal generated descriptor that is visible on the card statement of the payer. type: string application_context: type: object properties: brand_name: description: The label that overrides the business name in the PayPal account on the PayPal site. type: string locale: description: The locale pages that appear based on language and country code. PayPal supports a five-character code. For example, ja-JP. type: string landing_page: description: The type of landing page to show on the PayPal site for customer checkout. Use values LOGIN, BILLING, or NO_PREFERENCE. type: string shipping_preference: description: The shipping preference. Use SET_PROVIDED_ADDRESS value. This parameter does allow the user to change their address on PayPal site. type: string user_action: description: If you set `useraction=commit` in the query string, the flow redirects the buyer to the PayPal payment page and displays a Pay Now button. When the shopper clicks **Pay Now**, call `DoExpressCheckoutPayment` to complete the payment without additional interaction from the shopper. Choose this flow when you know the final payment amount when you initiate the checkout flow. type: string return_url: description: The callback URL for PayPal to redirect the user in the case of approved payment. type: string cancel_url: description: The callback URL for PayPal to redirect user in the case a cancelled payment. type: string CustomAttributes: title: CustomAttributes type: object description: "Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n \"is_member\": {\n \"type\": \"boolean\",\n \"value\": true\n },\n \"membership_level\": {\n \"type\": \"string\",\n \"value\": \"premium\"\n }\n}\n```\n" additionalProperties: type: object required: - type - value properties: type: type: string description: The type of the custom attribute value. enum: - string - integer - boolean - float value: description: The value of the custom attribute. type: - string - boolean - number ItemSettings: title: ItemSettings type: object properties: separate_items_by_location: description: When set to true, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When false (default), items with the same SKU are merged and the location is updated to the most recent value. type: boolean examples: - false Data.ManualPayment: title: Data.ManualPayment required: - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the type of payment gateway. You must use `manual`. type: string const: manual paymentmethod_meta: type: object properties: custom_reference: description: A reference associated with the payment method. This might include loyalty points or gift card identifiers. We recommend not to include personal information in this field. type: string name: description: A custom name associated with the payment method. type: string Response.Data: type: object properties: data: {} InventorySettings: title: InventorySettings type: object properties: defer_inventory_check: description: This parameter enables deferring inventory checks on the cart. This allows items to be added to or updating in the cart without checking stock levels. Inventory checks are still performed as normal on checkout type: boolean examples: - false RelationshipArray: title: RelationshipArray description: Array of relationships type: object properties: data: description: Individual relationships type: array items: $ref: '#/components/schemas/RelationshipItem' Data.StripePayment: title: Data.StripePayment required: - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the type of payment gateway. You must use `stripe`. type: string const: stripe options: type: object properties: receipt_email: description: The option to provide an email for Stripe receipts. Specify live mode to access this feature. type: string payment: description: The Stripe token or source. type: string securitySchemes: BearerToken: type: http scheme: bearer