Skip to main content

Transaction events

PaymentsAI dispatches transaction events whenever a payment is processed or declined. Use these events to update order status, trigger fulfillment, or initiate dunning logic server-side without polling the API.

Events​

Event typeWhen it fires
transaction-processedA transaction was processed by the gateway. A payment was captured or a refund was completed.
transaction-declinedA transaction was declined by the processor or issuer. Fires for each declined attempt, including during subscription dunning.

Payload​

Both events share the same payload shape:

type Event = {
  deduplicationId: string;
  type: 'transaction-processed' | 'transaction-declined';
  organizationId: string;
  metadata: Transaction;
};

See Schemas for the full Transaction type definition.

Common use cases​

  • Fulfill an order: Listen for transaction-processed where metadata.result === 'approved' and metadata.type === 'sale'.
  • Handle a refund: Listen for transaction-processed where metadata.type === 'refund'.
  • Dunning: Listen for transaction-declined on subscription payments and notify the customer to update their payment method.

Sequence in a first subscription flow​

For a subscription created with a new payment instrument:

  1. Customer completes the hosted payment form.
  2. transaction-processed fires for the first payment.
  3. subscription-activated fires when the subscription moves to active.

See Subscription events for the full sequence.