# Payment Transactions A `PaymentTransaction` in Violet is an object that represents the intent to collect payment from a customer for a specific Order, tracks the lifecycle of the payment process, and provides you with any specific payment information you may need on your end for payment processing. `PaymentTransaction`s are automatically generated when Orders are created and are visible are a part of the Order response. When an Order is created, if you are using Violet as your payment orchestrator, the `PaymentTransaction` object indicates information such as the following: * The unique identifier of the Order that this payment transaction is associated with. * Unique identifiers for the underlying Bags that this payment transaction is associated with. * Amount and currency that the shopper will be charged * Underlying payment provider being used to process the payment and related payouts. For example, `STRIPE`. * Payment provider specific transaction data, such as transaction and payment method identifiers in the payment provider system. This comes back as a part of the `metadata` field and may differ based on underlying payment provider. * Payment statuses associated with the order. * Errors, if any, associated with the payment transaction. The `capture_status` field on the `PaymentTransaction` indicates the current stage of the payment capture process for this Order. It progresses through the following statuses: {% stepper %} {% step %} **Requires Payment Method** A Payment Transaction Capture Status is in the `REQUIRES_PAYMENT_METHOD` state when it is first created and doesn't have a payment method. An Order cannot be submitted if a payment method has not been added. {% endstep %} {% step %} **Requires Authorization** A Payment Transaction Capture Status is in the `REQUIRES_AUTHORIZATION` state when it has a payment method that has not been authorized. Authorization verifies that funds are available on the attached payment method and places a hold. {% endstep %} {% step %} **Requires Action** A Payment Transaction Capture Status is in the `REQUIRES_ACTION` state when the payment method on the payment transaction requires additional steps, such as 3D secure. Not all payment transactions end up in this state. {% endstep %} {% step %} **Authorized** A Payment Transaction Capture Status is in the `AUTHORIZED` state when the payment method attached to this payment transaction has been authorized. Once a payment method has been authorized, the price of a cart cannot change. {% endstep %} {% step %} **Captured** A Payment Transaction Capture Status is in the `CAPTURED` state when the payment method attached to this payment transaction has been captured and the shopper has been charged. This state denotes a completed Order. {% endstep %} {% step %} **Failed** A Payment Transaction Capture Status is in the `FAILED` state when making a call to authorize or settle the payment method attached to this payment transaction, the payment provider responded with an error that cannot be reversed. {% endstep %} {% step %} **Refunded** A Payment Transaction Capture Status is in the `REFUNDED` state if a refund comes in for a Bag post Order submission and the full amount is refunded to the shopper. {% endstep %} {% step %} **Partially Refunded** A Payment Transaction Capture Status is in the `PARTIALLY_REFUNDED` state if a refund comes in for a Bag post Order submission and only a partial amount is refunded to the shopper. {% endstep %} {% step %} **Bypassed** A Payment Transaction Capture Status is in the `BYPASSED` state if Violet is not handling charging the shopper for this Order. This status is only present when `capture_method` is marked as `EXTERNAL`. {% endstep %} {% endstepper %} The `transfer_status` field on the `PaymentTransaction` indicates the current state of fund transfers to the associated parties in this Order, including channel commissions and any transfers to the Merchant. It progresses through the following statuses: {% stepper %} {% step %} **Pending** A Payment Transaction Transfer Status is in the `PENDING` state when transfers to associated parties have not been initiated. {% endstep %} {% step %} **Sent** A Payment Transaction Transfer Status is in the `SENT` state once all funds have been sent to the channel and merchant, post order submission. {% endstep %} {% step %} **Failed** A Payment Transaction Transfer Status is in the `FAILED` state if Violet is unable to transfer funds to the Merchant during Checkout. This could occur if the merchant has not set up a payout account, or if the payout account is not enabled for fund transfer. {% endstep %} {% step %} **Partially Reversed** A Payment Transaction Transfer Status is in the `PARTIALLY_REVERSED` state if a partial refund has been processed for this Order. This state denotes that funds originally sent as a part of Order placement have been partially reversed. {% endstep %} {% step %} **Reversed** A Payment Transaction Transfer Status is in the `REVERSED` state if a full refund has been processed for this Order. This state denotes that funds originally sent as a part of Order placement have all been reversed. {% endstep %} {% step %} **Bypassed** A Payment Transaction Transfer Status is in the `BYPASSED` state if Violet is not handling fund transfer to the channel or merchant. This status is only present when `transfer_method` is marked as `EXTERNAL`. {% endstep %} {% endstepper %} The following snippet illustrates how Payment Transactions appear as a part of the Order response. ```json { "id": 54652, "token": "758430be307a44d5b6b495779b54ef05", "errors": [], "app_id": 10193, "developer_id": 10122, ... "payment_transactions": [ { "id": 31713, "order_id": 54937, "payment_provider": "STRIPE", "payment_provider_transaction_id": "pi_3QKkJSK29KDiBVld1S9XTdtr", "payment_method_id": 10822, "payment_provider_payment_method_id": "pm_1QKkJSK29KDiBVldII3EL37H", "payment_intent_client_secret": "pi_3QKkJSK29KDiBVld1S9XTdtr_secret_6K8g71NIZf8b0ZvGZUwRFC042", "amount": 120000, "currency": "USD", "capture_status": "CAPTURED", "capture_method": "AUTOMATIC", "transfer_status": "SENT", "transfer_method": "AUTOMATIC", "metadata": { "payment_intent_client_secret": "pi_3QKkJSK29KDiBVld1S9XTdtr_secret_6K8g71NIZf8b0ZvGZUwRFC042", "payment_intent_id": "pi_3QKkJSK29KDiBVld1S9XTdtr" }, "related_bags": [ "64881" ], "errors": [], "date_created": "2024-11-13T17:25:14+0000", "date_last_modified": "2024-11-13T17:25:19+0000" } ], ... } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.violet.io/prism/payments/payments-during-checkout/payment-transactions.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.