feat: add wallet transaction details (#3339)

## Context

This PR enhances the handling of WalletTransactions by introducing
support for failed transactions and improving GraphQL access to
transaction data. The changes provide better visibility into payment
failures and their impact on invoices.

## Description

GraphQL Changes

- Added WalletTransactionResolver to allow retrieving a single wallet
transaction.
- Linked payments to an invoice 
- Added failed_at and linked invoice to WalletTransaction for better
tracking of failed transactions.

Backend Changes

- Introduced a new failed status for WalletTransaction to reflect
payment failures.
- Added failed_at timestamp to store when a transaction fails.
- Updated logic to handle payment failures:
- When a payment fails, the corresponding WalletTransaction is now
marked as failed with the failed_at timestamp.|

 ## Ongoing Refactor
Working on a separate PR to refactor how we retrieve the invoice for a
WalletTransaction so we always have invoice_id in transaction instead of
searching on the fees

Author: brunomiguelpinto

app/graphql/resolvers/wallet_transaction_resolver.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Resolvers
+  class WalletTransactionResolver < Resolvers::BaseResolver
+    include AuthenticableApiUser
+    include RequiredOrganization
+
+    description "Query a single wallet transaction"
+
+    argument :id, ID, required: true, description: "Unique ID of the wallet transaction"
+
+    type Types::WalletTransactions::Object, null: true
+
+    def resolve(id:)
+      current_organization.wallet_transactions.includes(:invoice).find(id)
+    rescue ActiveRecord::RecordNotFound
+      not_found_error(resource: "wallet_transaction")
+    end
+  end
+end

app/graphql/types/invoices/object.rb

@@ -70,6 +70,7 @@ class Object < Types::BaseObject
       field :integration_salesforce_syncable, GraphQL::Types::Boolean, null: false
       field :integration_syncable, GraphQL::Types::Boolean, null: false
       field :payable_type, GraphQL::Types::String, null: false
+      field :payments, [Types::Payments::Object], null: true
       field :tax_provider_voidable, GraphQL::Types::Boolean, null: false
 
       def payable_type
@@ -80,6 +81,10 @@ def applied_taxes
         object.applied_taxes.order(tax_rate: :desc)
       end
 
+      def payments
+        object.payments.order(updated_at: :desc)
+      end
+
       def integration_syncable
         object.should_sync_invoice? &&
           object.integration_resources

app/graphql/types/query_type.rb

@@ -73,6 +73,7 @@ class QueryType < Types::BaseObject
     field :tax, resolver: Resolvers::TaxResolver
     field :taxes, resolver: Resolvers::TaxesResolver
     field :wallet, resolver: Resolvers::WalletResolver
+    field :wallet_transaction, resolver: Resolvers::WalletTransactionResolver
     field :wallet_transactions, resolver: Resolvers::WalletTransactionsResolver
     field :wallets, resolver: Resolvers::WalletsResolver
     field :webhook_endpoint, resolver: Resolvers::WebhookEndpointResolver

app/graphql/types/wallet_transactions/object.rb

@@ -16,9 +16,18 @@ class Object < Types::BaseObject
       field :transaction_type, Types::WalletTransactions::TransactionTypeEnum, null: false
 
       field :created_at, GraphQL::Types::ISO8601DateTime, null: false
+      field :failed_at, GraphQL::Types::ISO8601DateTime, null: true
+      field :invoice, Types::Invoices::Object, null: true
       field :metadata, [Types::WalletTransactions::MetadataObject], null: true
       field :settled_at, GraphQL::Types::ISO8601DateTime, null: true
       field :updated_at, GraphQL::Types::ISO8601DateTime, null: false
+
+      def invoice
+        return object.invoice if object.invoice_id.present?
+
+        fee = Fee.find_by(invoiceable_id: object.id, invoiceable_type: "WalletTransaction")
+        fee&.invoice
+      end
     end
   end
 end

app/jobs/invoices/prepaid_credit_job.rb

@@ -7,10 +7,15 @@ class PrepaidCreditJob < ApplicationJob
     retry_on ActiveRecord::StaleObjectError, wait: :polynomially_longer, attempts: 6
     unique :until_executed, on_conflict: :log
 
-    def perform(invoice)
+    def perform(invoice, payment_status = :succeeded)  # Default to :succeeded for old jobs
       wallet_transaction = invoice.fees.find_by(fee_type: "credit")&.invoiceable
-      Wallets::ApplyPaidCreditsService.call(wallet_transaction:)
-      Invoices::FinalizeOpenCreditService.call(invoice:)
+
+      if payment_status.to_sym == :succeeded
+        Wallets::ApplyPaidCreditsService.call(wallet_transaction:)
+        Invoices::FinalizeOpenCreditService.call(invoice:)
+      elsif payment_status.to_sym == :failed
+        WalletTransactions::MarkAsFailedService.new(wallet_transaction:).call
+      end
     end
   end
 end

app/models/wallet_transaction.rb

@@ -11,7 +11,8 @@ class WalletTransaction < ApplicationRecord
 
   STATUSES = [
     :pending,
-    :settled
+    :settled,
+    :failed
   ].freeze
 
   TRANSACTION_STATUSES = [
@@ -46,6 +47,12 @@ def amount_cents
   def unit_amount_cents
     wallet.rate_amount * wallet.currency_for_balance.subunit_to_unit
   end
+
+  def mark_as_failed!(timestamp = Time.zone.now)
+    return if failed?
+
+    update!(status: :failed, failed_at: timestamp)
+  end
 end
 
 # == Schema Information
@@ -55,6 +62,7 @@ def unit_amount_cents
 #  id                                  :uuid             not null, primary key
 #  amount                              :decimal(30, 5)   default(0.0), not null
 #  credit_amount                       :decimal(30, 5)   default(0.0), not null
+#  failed_at                           :datetime
 #  invoice_requires_successful_payment :boolean          default(FALSE), not null
 #  metadata                            :jsonb
 #  settled_at                          :datetime

app/serializers/v1/wallet_transaction_serializer.rb

@@ -13,6 +13,7 @@ def serialize
         amount: model.amount,
         credit_amount: model.credit_amount,
         settled_at: model.settled_at&.iso8601,
+        failed_at: model.failed_at&.iso8601,
         created_at: model.created_at.iso8601,
         invoice_requires_successful_payment: model.invoice_requires_successful_payment?,
         metadata: model.metadata

app/services/invoices/update_service.rb

@@ -80,9 +80,9 @@ def valid_payment_status?(payment_status)
 
     def handle_prepaid_credits(payment_status)
       return unless invoice.invoice_type&.to_sym == :credit
-      return unless payment_status&.to_sym == :succeeded
+      return unless %i[succeeded failed].include?(payment_status.to_sym)
 
-      Invoices::PrepaidCreditJob.perform_later(invoice)
+      Invoices::PrepaidCreditJob.perform_later(invoice, payment_status)
     end
 
     def valid_metadata_count?(metadata:)

app/services/wallet_transactions/mark_as_failed_service.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module WalletTransactions
+  class MarkAsFailedService < BaseService
+    def initialize(wallet_transaction:)
+      @wallet_transaction = wallet_transaction
+      super
+    end
+
+    def call
+      return result unless wallet_transaction
+      return result if wallet_transaction.status == "failed"
+
+      wallet_transaction.mark_as_failed!
+      SendWebhookJob.perform_later("wallet_transaction.updated", wallet_transaction)
+      result.wallet_transaction = wallet_transaction
+      result
+    end
+
+    private
+
+    attr_reader :wallet_transaction
+  end
+end

db/migrate/20250318093216_add_failed_at_to_wallet_transactions.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class AddFailedAtToWalletTransactions < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!
+  def change
+    add_column :wallet_transactions, :failed_at, :datetime
+  end
+end

db/migrate/20250318175216_mark_pending_wallet_transactions_as_failed.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+class MarkPendingWalletTransactionsAsFailed < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!
+
+  def up
+    # Update transactions using the latest `updated_at` from failed payments (if available)
+    safety_assured do
+      execute <<~SQL.squish
+        UPDATE wallet_transactions wt
+        SET status = 2,
+            failed_at = (
+                SELECT MAX(p.updated_at)
+                FROM fees f
+                INNER JOIN invoices i ON i.id = f.invoice_id
+                INNER JOIN payments p ON p.payable_id = i.id
+                WHERE f.invoiceable_id = wt.id
+                  AND f.invoiceable_type = 'WalletTransaction'
+                  AND i.payment_status = 2
+                  AND p.payable_payment_status = 'failed'
+            )
+        WHERE wt.status = 0
+          AND EXISTS (
+                SELECT 1
+                FROM fees f
+                INNER JOIN invoices i ON i.id = f.invoice_id
+                INNER JOIN payments p ON p.payable_id = i.id
+                WHERE f.invoiceable_id = wt.id
+                  AND f.invoiceable_type = 'WalletTransaction'
+                  AND i.payment_status = 2
+                  AND p.payable_payment_status = 'failed'
+            );
+      SQL
+    end
+
+    # Then update transactions using `invoices.updated_at` if no failed payment exists
+    safety_assured do
+      execute <<~SQL.squish
+        UPDATE wallet_transactions wt
+        SET status = 2,
+            failed_at = (
+                SELECT MAX(i.updated_at)
+                FROM fees f
+                INNER JOIN invoices i ON i.id = f.invoice_id
+                WHERE f.invoiceable_id = wt.id
+                  AND f.invoiceable_type = 'WalletTransaction'
+                  AND i.payment_status = 2
+                  AND NOT EXISTS (
+                      SELECT 1
+                      FROM payments p
+                      WHERE p.payable_id = i.id
+                  )
+            )
+        WHERE wt.status = 0
+          AND EXISTS (
+              SELECT 1
+              FROM fees f
+              INNER JOIN invoices i ON i.id = f.invoice_id
+              WHERE f.invoiceable_id = wt.id
+                AND f.invoiceable_type = 'WalletTransaction'
+                AND i.payment_status = 2
+                AND NOT EXISTS (
+                    SELECT 1
+                    FROM payments p
+                    WHERE p.payable_id = i.id
+                )
+          );
+      SQL
+    end
+  end
+
+  def down
+    # do nothing
+  end
+end