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 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:
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.
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.
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.
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.
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.
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.
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.
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?