Fix return URL for headless storefronts and handle redirect result server-side (#57)

* Fix return URL for headless storefronts and handle redirect result server-side

**Default return URL**: Use `store.storefront_url` (first AllowedOrigin,
falling back to formatted_url) instead of the Spree engine route helper
which generates URLs with incorrect scheme/port for headless setups.
Legacy mode (`use_legacy_adyen_payment_sessions`) keeps the old engine
route behaviour.

**Redirect result handling**: `complete_payment_session` now accepts
`redirect_result` in `external_data` for redirect-based payment methods
(Klarna, iDEAL, 3DS). When the storefront passes the `redirectResult`
from Adyen's return URL, the gateway resolves it to a `sessionResult`
server-side via `/payments/details`, keeping the storefront
provider-agnostic.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Address review: fail fast on missing session_result, drop unused param

- Raise GatewayError when neither session_result nor redirect_result
  resolves, instead of passing nil to the Adyen API
- Remove unused payment_session param from resolve_session_result_from_redirect
- Fix hash indentation in payments_details call

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add tests for complete_payment_session redirect_result handling

- with session_result: completes normally
- with redirect_result in external_data: resolves via /payments/details
  then completes
- with neither: raises GatewayError
- when redirect_result cannot be resolved: raises GatewayError

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: damianlegawiec

app/models/spree_adyen/gateway/payment_sessions.rb

@@ -65,10 +65,19 @@ def update_payment_session(payment_session:, amount: nil, external_data: {})
       # (called by the storefront or by the webhook handler).
       #
       # @param payment_session [Spree::PaymentSessions::Adyen] the session to complete
-      # @param params [Hash] must include :session_result
+      # @param params [Hash] must include :session_result or external_data with :redirect_result
+      # @raise [Spree::Core::GatewayError] if neither session_result nor redirect_result can be resolved
       def complete_payment_session(payment_session:, params: {})
         session_result = params[:session_result] || params['session_result']
 
+        if session_result.blank?
+          external_data = params[:external_data] || params['external_data'] || {}
+          redirect_result = external_data[:redirect_result] || external_data['redirect_result']
+          session_result = resolve_session_result_from_redirect(redirect_result) if redirect_result.present?
+        end
+
+        raise Spree::Core::GatewayError, 'session_result or redirect_result is required' if session_result.blank?
+
         response = payment_session_result(payment_session.external_id, session_result)
         status = response.params.fetch('status')
 
@@ -102,8 +111,24 @@ def complete_payment_session(payment_session:, params: {})
 
       private
 
+      # Resolves a sessionResult from a redirectResult by calling Adyen's /payments/details endpoint.
+      # In the sessions flow, Adyen processes the redirect server-side. We call /payments/details
+      # with the redirectResult to finalize the payment and get the sessionResult.
+      def resolve_session_result_from_redirect(redirect_result)
+        response = send_request do
+          client.checkout.payments_api.payments_details(
+            details: { redirectResult: redirect_result }
+          )
+        end
+        response.response&.dig('sessionResult')
+      end
+
       def default_return_url(order)
-        Spree::Core::Engine.routes.url_helpers.redirect_adyen_payment_session_url(host: order.store.url_or_custom_domain)
+        if SpreeAdyen::Config[:use_legacy_adyen_payment_sessions]
+          Spree::Core::Engine.routes.url_helpers.redirect_adyen_payment_session_url(host: order.store.url_or_custom_domain)
+        else
+          "#{order.store.storefront_url}/adyen/payment_sessions/redirect"
+        end
       end
     end
   end

app/models/spree_adyen/payment_session.rb

@@ -82,7 +82,7 @@ def set_default_channel
     def set_return_url
       return if order.blank?
 
-      self.return_url = Spree::Core::Engine.routes.url_helpers.redirect_adyen_payment_session_url(host: order.store.url_or_custom_domain)
+      self.return_url = "#{order.store.storefront_url}/adyen/payment_sessions/redirect"
     end
 
     def expiration_date_cannot_be_in_the_past_or_later_than_24_hours

spec/models/spree_adyen/gateway_spec.rb

@@ -658,6 +658,71 @@
     end
   end
 
+  describe '#complete_payment_session' do
+    let(:order) { create(:order_with_line_items, store: store) }
+    let!(:payment_session) do
+      Spree::PaymentSessions::Adyen.create!(
+        order: order,
+        payment_method: gateway,
+        amount: order.total,
+        currency: order.currency,
+        status: 'pending',
+        external_id: 'CS4FBB6F827EC53AC7',
+        external_data: { 'session_data' => 'test', 'channel' => 'Web' }
+      )
+    end
+
+    context 'with session_result' do
+      it 'completes the payment session' do
+        VCR.use_cassette('payment_session_results/success/completed') do
+          gateway.complete_payment_session(payment_session: payment_session, params: { session_result: 'resultData' })
+          expect(payment_session.reload.status).to eq('completed')
+        end
+      end
+    end
+
+    context 'with redirect_result in external_data' do
+      before do
+        allow(gateway).to receive(:resolve_session_result_from_redirect)
+          .with('redirectResultToken')
+          .and_return('resultData')
+      end
+
+      it 'resolves session_result from redirect_result and completes' do
+        VCR.use_cassette('payment_session_results/success/completed') do
+          gateway.complete_payment_session(
+            payment_session: payment_session,
+            params: { external_data: { redirect_result: 'redirectResultToken' } }
+          )
+          expect(payment_session.reload.status).to eq('completed')
+        end
+      end
+    end
+
+    context 'with neither session_result nor redirect_result' do
+      it 'raises a gateway error' do
+        expect {
+          gateway.complete_payment_session(payment_session: payment_session, params: {})
+        }.to raise_error(Spree::Core::GatewayError, 'session_result or redirect_result is required')
+      end
+    end
+
+    context 'when redirect_result cannot be resolved' do
+      before do
+        allow(gateway).to receive(:resolve_session_result_from_redirect).and_return(nil)
+      end
+
+      it 'raises a gateway error' do
+        expect {
+          gateway.complete_payment_session(
+            payment_session: payment_session,
+            params: { external_data: { redirect_result: 'bad_token' } }
+          )
+        }.to raise_error(Spree::Core::GatewayError, 'session_result or redirect_result is required')
+      end
+    end
+  end
+
   describe '#parse_webhook_event' do
     let(:order) { create(:order_with_line_items, store: store) }
     let!(:payment_session) do

spec/models/spree_adyen/payment_session_spec.rb

@@ -172,12 +172,8 @@
     end
 
     describe 'set_return_url' do
-      before do
-        allow(store).to receive(:url_or_custom_domain).and_return('url-or-custom-domain.com')
-      end
-
-      it 'sets the redirect url' do
-        expect { payment_session.validate }.to change(payment_session, :return_url).to('http://url-or-custom-domain.com/adyen/payment_sessions/redirect')
+      it 'sets the redirect url using store storefront_url' do
+        expect { payment_session.validate }.to change(payment_session, :return_url).to("#{store.storefront_url}/adyen/payment_sessions/redirect")
       end
     end
   end

spec/requests/spree/api/v2/storefront/adyen/payment_sessions_spec.rb

@@ -98,7 +98,7 @@
               expect(json_data['attributes']['client_key']).to eq('test_client_key')
               expect(json_data['attributes']['adyen_data']).to be_present
               expect(json_data['attributes']['channel']).to eq('Web') # default channel
-              expect(json_data['attributes']['return_url']).to eq('http://www.example.com/adyen/payment_sessions/redirect') # default channel
+              expect(json_data['attributes']['return_url']).to eq("#{store.storefront_url}/adyen/payment_sessions/redirect")
 
               # Verify relationships
               expect(json_data['relationships']['order']['data']['id']).to eq(order.id.to_s)