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 PaymentTransction object indicates information such as the following:

  • The unique identifier of the Order that this payment transaction is assocaited with.
  • Unique identifiers for the underlying Bags that this payment transaction is assocaited 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.
  • The current payment status of the Order
  • Errors, if any, associated with the payment transaction.

As you progress through the Order, the PaymentTransaction transitions through the following statuses:

1

Requires Payment Method

A Payment Transaction 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 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 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 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 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 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 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 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.

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": 31481,
            "order_id": 54652,
            "payment_provider": "STRIPE",
            "payment_provider_transaction_id": "pi_123456789asdfghjkl",
            "payment_method_id": 10650,
            "payment_provider_payment_method_id": "pm_123456789asdfghjkl",
            "amount": 120000,
            "metadata": {
                "payment_intent_client_secret": "pi_123456789asdfghjkl_secret_123456789asdfghjkl",
                "payment_intent_id": "pi_123456789asdfghjkl"
            },
            "currency": "USD",
            "status": "CAPTURED",
            "errors": [],
            "date_created": "2024-07-08T14:25:52+0000",
            "date_last_modified": "2024-07-08T14:25:57+0000"
        }
    ],
    ...
}

Was this page helpful?

Fee StructureSupported Currencies