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.

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:

1

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.

2

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.

3

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.

4

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.

5

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.

6

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.

7

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.

8

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.

9

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.

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:

1

Pending

A Payment Transaction Transfer Status is in the PENDING state when transfers to associated parties have not been initiated.

2

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.

3

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.

4

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.

5

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.

6

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.

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