Payment Transactions

Payment Transaction webhooks notify your application about changes to the capture status of payment transactions during checkout. These events enable you to monitor the lifecycle of shopper funds being captured, refunded, or partially refunded.

Overview

Payment Transaction webhooks specifically relate to payment transaction capture updates. They track the status of funds captured from shoppers during the checkout process.

Learn more about Payment Transactions in the Payment Transactions documentation.

Available Events

PAYMENT_TRANSACTION_CAPTURE_STATUS_UPDATED

Trigger: A catch-all event for any changes to the capture_status of a PaymentTransaction.

Use Case: Subscribe to this event to:

  • Monitor all payment status changes

  • Track payment lifecycle comprehensively

  • Log payment state transitions

  • Trigger payment reconciliation

  • Update order payment status

When to use specific events instead: If you only need to track specific capture status changes, subscribe to the more specific events (PAYMENT_TRANSACTION_CAPTURE_STATUS_AUTHORIZED, PAYMENT_TRANSACTION_CAPTURE_STATUS_CAPTURED, PAYMENT_TRANSACTION_CAPTURE_STATUS_REFUNDED, PAYMENT_TRANSACTION_CAPTURE_STATUS_PARTIALLY_REFUNDED, or PAYMENT_TRANSACTION_CAPTURE_STATUS_FAILED) instead of this generic event.

PAYMENT_TRANSACTION_CAPTURE_STATUS_AUTHORIZED

Trigger: When a payment is authorized but not yet captured, and the capture_status of a PaymentTransaction moves to AUTHORIZED.

Use Case: Monitor this event to:

  • Track payment authorization success

  • Confirm funds are reserved for capture

  • Update order status to show payment authorized

  • Log authorization timestamps

  • Monitor authorization-to-capture delays

Important: Authorization means the payment method is validated and funds are reserved, but not yet captured. The funds will be captured later (typically at fulfillment time). Authorizations can expire if not captured within a certain timeframe (usually 7 days for credit cards).

Next Step: Wait for PAYMENT_TRANSACTION_CAPTURE_STATUS_CAPTURED event when funds are actually captured.

PAYMENT_TRANSACTION_CAPTURE_STATUS_CAPTURED

Trigger: When funds are successfully captured from the shopper, and the capture_status of a PaymentTransaction moves to CAPTURED.

Use Case: Subscribe to this event to:

  • Confirm successful payment capture

  • Update financial records with captured amounts

  • Trigger fulfillment workflows (payment secured)

  • Calculate actual revenue

  • Update order payment status to captured

  • Begin commission calculations

Important: This is the definitive event indicating funds have been successfully captured and are now available for transfer to merchants. This typically occurs after order placement or at fulfillment time.

Flow: This event usually follows PAYMENT_TRANSACTION_CAPTURE_STATUS_AUTHORIZED and precedes TRANSFER_SENT events.

PAYMENT_TRANSACTION_CAPTURE_STATUS_REFUNDED

Trigger: When a shopper is refunded and the capture_status of a PaymentTransaction moves to REFUNDED.

Use Case: Monitor this event to:

  • Track full refunds

  • Update order refund status

  • Reconcile payment records

  • Trigger refund confirmation emails

  • Update financial reporting

  • Adjust commission calculations

Important: This event indicates a complete refund of the payment transaction. For partial refunds, see PAYMENT_TRANSACTION_CAPTURE_STATUS_PARTIALLY_REFUNDED.

PAYMENT_TRANSACTION_CAPTURE_STATUS_PARTIALLY_REFUNDED

Trigger: When a shopper is partially refunded and the capture_status of a PaymentTransaction moves to PARTIALLY_REFUNDED.

Use Case: Subscribe to this event to:

  • Track partial refunds

  • Calculate remaining captured amounts

  • Update order payment status

  • Reconcile financial records

  • Adjust commission calculations proportionally

  • Send partial refund notifications

Note: A payment transaction can be partially refunded multiple times until the full amount is refunded, at which point it becomes REFUNDED.

PAYMENT_TRANSACTION_CAPTURE_STATUS_FAILED

Trigger: When a payment capture attempt fails, and the capture_status of a PaymentTransaction moves to FAILED.

Use Case: Monitor this event to:

  • Alert teams to payment failures immediately

  • Notify customers of payment issues

  • Trigger retry mechanisms or alternative payment collection

  • Track payment failure rates and reasons

  • Update order status to reflect payment failure

  • Investigate fraud or technical issues

Common Failure Reasons:

  • Insufficient funds in customer account

  • Invalid or expired payment method

  • Payment method declined by issuer

  • Fraud prevention triggers

  • Technical issues with payment processor

  • Payment authorization expired before capture

Important: Payment capture failures typically require immediate action, as the order cannot be fulfilled without successful payment. You may need to request alternative payment from the customer or cancel the order.

Impact: When a payment capture fails, the order typically cannot proceed. The customer needs to provide an alternative payment method, or the order should be cancelled.

Understanding Capture Status

The capture_status field on a PaymentTransaction represents the current state of the captured funds:

  • AUTHORIZED - Payment method validated and funds reserved, but not yet captured

  • CAPTURED - Funds have been successfully captured from the shopper

  • PARTIALLY_REFUNDED - Some funds have been returned to the shopper

  • REFUNDED - All captured funds have been returned to the shopper

  • FAILED - Payment capture attempt failed

Related Documentation

Best Practices

  1. Use specific events for different capture states - Instead of only subscribing to PAYMENT_TRANSACTION_CAPTURE_STATUS_UPDATED, subscribe to specific events (AUTHORIZED, CAPTURED, REFUNDED, PARTIALLY_REFUNDED, FAILED) for clearer business logic and easier debugging.

  2. Monitor authorization expiration - Authorizations typically expire after 7 days. Track the time between AUTHORIZED and CAPTURED events to identify potential authorization expiration issues.

  3. Handle payment failures immediately - FAILED events require prompt action. Implement alerting and customer notification workflows to address payment failures quickly.

  4. Track refund amounts - When processing partial refunds, maintain a running total of refunded amounts to calculate the remaining captured balance.

  5. Coordinate with Transfer events - Payment Transaction captures correspond with Transfer events. Monitor both for complete financial visibility: CAPTURED → TRANSFER_SENT, REFUNDED → TRANSFER_REVERSED.

  6. Handle multiple partial refunds - A transaction can be partially refunded multiple times. Ensure your system can handle sequential partial refund events.

  7. Update commission calculations - Refunds (full or partial) should adjust any commission or fee calculations to reflect the actual captured amount.

  8. Reconcile with order events - Payment Transaction events often occur alongside Order events. Correlate these events: CAPTURED with ORDER_COMPLETED, REFUNDED with ORDER_REFUNDED.

  9. Process asynchronously - Payment processing can be time-consuming. Return a 2xx response quickly and process the payment details in the background.

  10. Log capture failures with context - When receiving FAILED events, log the failure reason and context to help with debugging and customer support.

Webhook Headers

Payment Transaction webhooks include the default webhook headers, plus:

X-Violet-Order-Id

Contains the Violet Order ID associated with this payment transaction.

X-Violet-Entity-Id

Contains the Payment Transaction ID for the transaction that was updated.

Common Integration Patterns

Payment Capture Flow

PAYMENT_TRANSACTION_CAPTURE_STATUS_AUTHORIZED → Validate authorization → Reserve inventory
PAYMENT_TRANSACTION_CAPTURE_STATUS_CAPTURED → Confirm payment → Begin fulfillment → Calculate revenue
PAYMENT_TRANSACTION_CAPTURE_STATUS_FAILED → Alert team → Notify customer → Request new payment

Refund Processing

PAYMENT_TRANSACTION_CAPTURE_STATUS_REFUNDED → Update order status → Adjust commissions → Notify customer
PAYMENT_TRANSACTION_CAPTURE_STATUS_PARTIALLY_REFUNDED → Calculate remaining amount → Update records

Financial Reconciliation

PAYMENT_TRANSACTION_CAPTURE_STATUS_UPDATED → Fetch full transaction details → Reconcile with accounting system
PAYMENT_TRANSACTION_CAPTURE_STATUS_CAPTURED → Record revenue → Update financial reports
PAYMENT_TRANSACTION_CAPTURE_STATUS_REFUNDED → Reverse revenue recognition → Update reports

Commission Adjustment

PAYMENT_TRANSACTION_CAPTURE_STATUS_CAPTURED → Calculate commission → Schedule payout
PAYMENT_TRANSACTION_CAPTURE_STATUS_REFUNDED → Calculate commission reversal → Update merchant payout
PAYMENT_TRANSACTION_CAPTURE_STATUS_PARTIALLY_REFUNDED → Prorate commission → Adjust distributions

Coordinating with Other Events

Payment Transaction events often occur in conjunction with other webhook events:

Successful Payment Flow

ORDER_ACCEPTED → Order placed
PAYMENT_TRANSACTION_CAPTURE_STATUS_AUTHORIZED → Payment authorized
PAYMENT_TRANSACTION_CAPTURE_STATUS_CAPTURED → Funds captured
TRANSFER_SENT → Funds sent to merchant
ORDER_SHIPPED → Order fulfilled

Failed Payment Flow

ORDER_ACCEPTED → Order placed
PAYMENT_TRANSACTION_CAPTURE_STATUS_AUTHORIZED → Payment authorized
PAYMENT_TRANSACTION_CAPTURE_STATUS_FAILED → Capture fails
ORDER_CANCELLED → Order cancelled due to payment failure

Full Refund Flow

ORDER_REFUNDED → Payment system processes refund
PAYMENT_TRANSACTION_CAPTURE_STATUS_REFUNDED → Funds returned to customer
TRANSFER_REVERSED → Funds reversed from merchant

Partial Refund Flow

ORDER_REFUNDED (partial) → Payment system processes partial refund
PAYMENT_TRANSACTION_CAPTURE_STATUS_PARTIALLY_REFUNDED → Partial funds returned
TRANSFER_PARTIALLY_REVERSED → Partial funds reversed from merchant

Consider monitoring all related event types for a complete picture of payment operations.

PreviousPayout AccountsNextTransfers

Last updated

Was this helpful?