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. PaymentTransactions 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.

​

Flexible Payment and Transfer Strategies

Violet offers flexible options to implement more precise and tailored payment strategies. The PaymentTransaction model exposes the capture_method and transfer_method applied to the Order. This can be set at either the Channel or Merchant level.

• Capture Method — This defines how the shopper’s payment method is charged. Available options are AUTOMATIC, EXTERNAL and CUSTOM.
  • Automatic — Violet generates a pending charge on the shopper’s payment method and automatically captures it once the order is successfully submitted.
  • External — The channel manages all aspects of fund capture from the shopper. Violet does not take any action with Stripe to charge the shopper in this scenario and assumes payment has been captured directly by you.
  • Custom — Violet creates a pending charge on the shopper’s payment method but will only capture funds when triggered separately by the channel. This setup is ideal if you want the shopper to be charged once specific conditions have been met. For example, capture funds only after the merchant fulfills the order. (Support forCUSTOM capture will be released in a future iteration of this feature. Timing TBD.)
• Transfer Method — This determines how Merchants receive funds for each order placed through Violet. Available options are AUTOMATIC, EXTERNAL and CUSTOM.
  • Automatic — Violet generates and processes the transfer of funds to Merchants automatically as part of each order submission, ensuring merchants are paid in an automated fashion.
  • External — The Channel fully manages Merchant transfers and payouts for orders placed through Violet. Violet does not generate any transfer, distribution or payout records for bags and orders associated with these Merchants.
  • Custom — Violet creates Distribution records for Merchants but only transfers funds when prompted by the channel. While merchants can view their pending Distributions in the Merchant Dashboard, they will not receive funds until the channel initiates the transfer of funds. (APIs for CUSTOM transfer initiation will be launched on Nov 18.)

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:

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:

The following snippet illustrates how Payment Transactions appear as a part of the Order response.

{
    "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"
        }
    ],
    ...
}