mpp-rb 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7accbb98302b70cc76e32afc99bf2b5672c445194f79e9fd1cdfb0e5d7f058dd
-  data.tar.gz: 3538fdc0cd0851816ac29f294de441e18fefb45f0bd00b44cad6295ca6a1e1f1
+  metadata.gz: c71efa5e58021d08e4ed10c0156ed9b140923b0f3ebeb5ce6b42839594c27dd6
+  data.tar.gz: d40e3c4994086eea6f2c11023f47fda635637ae6815dc263d63c12ca10235ae8
 SHA512:
-  metadata.gz: b6cd8af4a9376b0db632aab578f1d9fb0e9e6d3327c926e40f35badb16750d06a15774fe7444debde1a402a7d3b51133d25bfd43d577de726fe646c35bc4f522
-  data.tar.gz: 2997bf04f49594dce0246c917075d5aba8a9f974e6ed4ff6cda586e8ae9361db110cf5197ee977fa8d795b5f0affc701f34170f4c75654f5485853608fb6776c
+  metadata.gz: af6ba306f236fb01dd140f63ce51c764fdee655a7f1282d7adad87d8586e4838d43f096ca79a4053dbab703afdc6fa1806d3e20ea6b6afa75c7c70bf6d3885f3
+  data.tar.gz: db9bc204d61dcdb4c3e9d0b8f9034f935dd38d4291b71b37e61a29889240b27667400e5c48333d2cf39e2d6513b5af70368a354a8a20fd5a543558b07b68f700

data/README.md

@@ -2,7 +2,7 @@
 
 Ruby SDK for the [**Machine Payments Protocol**](https://mpp.dev)
 
-[![Gem Version](https://img.shields.io/gem/v/mpp.svg)](https://rubygems.org/gems/mpp-rb)
+[![Gem Version](https://img.shields.io/gem/v/mpp-rb.svg)](https://rubygems.org/gems/mpp-rb)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 ## Documentation
@@ -68,6 +68,35 @@ transport = Mpp::Client::Transport.new(
 response = transport.request(:get, "https://mpp.dev/api/ping/paid")
 ```
 
+### Event hooks
+
+Register hooks to observe the automatic payment lifecycle. Each registration returns an unsubscribe proc.
+
+```ruby
+server.on_challenge_created do |payload|
+  puts "challenge: #{payload[:challenge].id}"
+end
+
+server.on_payment_success do |payload|
+  puts "paid: #{payload[:receipt].reference}"
+end
+
+transport.on_challenge_received do |payload|
+  puts "received: #{payload[:challenge].id}"
+  nil
+end
+
+transport.on_payment_response do |payload|
+  puts "retry status: #{payload[:response].code}"
+end
+
+transport.on("*") do |event|
+  puts "payment event: #{event.name}"
+end
+```
+
+Client events are `challenge.received`, `credential.created`, `payment.response`, and `payment.failed`. Server events are `challenge.created`, `payment.success`, and `payment.failed`.
+
 ### Rack Middleware
 
 ```ruby
@@ -123,10 +152,13 @@ Built on the ["Payment" HTTP Authentication Scheme](https://datatracker.ietf.org
 
 ## Releasing
 
-1. Update the version in `lib/mpp/version.rb`
-2. Commit: `git commit -am "v0.x.x"`
-3. Tag: `git tag v0.x.x`
-4. Push: `git push origin main --tags`
+1. Create a release PR:
+   - Update the version in `lib/mpp/version.rb`
+   - Run `bundle lock --update mpp-rb` in the root and each `examples/` subdirectory
+   - Commit and open a PR to verify CI passes
+2. Merge the PR
+3. Tag the merge commit: `git tag v0.x.x`
+4. Push the tag: `git push origin --tags`
 
 ## License
 

data/lib/mpp/body_digest.rb

@@ -21,7 +21,7 @@ module Mpp
       when String
         # use as-is
       end
-      body = body.encode(Encoding::UTF_8) if body.is_a?(String)
+      body = body.b if body.is_a?(String)
       digest = OpenSSL::Digest::SHA256.digest(body)
       encoded = Base64.strict_encode64(digest)
       "sha-256=#{encoded}"

data/lib/mpp/challenge.rb

@@ -58,20 +58,95 @@ module Mpp
       Mpp::Parsing.parse_www_authenticate(header)
     end
 
-    # Parse multiple Payment challenges from a merged WWW-Authenticate header.
-    # Handles RFC 9110 §11.6.1 comma-separated authentication schemes.
+    # Split a merged WWW-Authenticate header value into the individual
+    # `Payment ...` challenge chunks it contains, handling RFC 9110 §11.6.1
+    # comma-separated authentication schemes. Returns the raw chunk strings so
+    # callers can parse each challenge independently; a malformed chunk then
+    # does not prevent the remaining chunks from being considered.
+    def self.www_authenticate_chunks(header)
+      payment_scheme_indices(header).map do |start_idx|
+        # End each chunk at the next scheme boundary of any kind, so an
+        # interleaved non-Payment scheme (e.g. "Payment ..., Bearer ...,
+        # Payment ...") is not folded into the preceding Payment challenge.
+        end_idx = next_auth_scheme_index(header, start_idx + "Payment".length) || header.length
+        T.must(header[start_idx...end_idx]).sub(/,\s*$/, "")
+      end
+    end
+
+    # Parse every Payment challenge from a merged WWW-Authenticate header.
+    # Raises Mpp::ParseError on the first malformed chunk; callers that need to
+    # tolerate a malformed challenge among valid ones should iterate
+    # `www_authenticate_chunks` and parse each chunk independently instead.
     def self.from_www_authenticate_list(header)
+      www_authenticate_chunks(header).map { |chunk| from_www_authenticate(chunk) }
+    end
+
+    def self.payment_scheme_indices(header)
       indices = []
-      header.scan(/Payment\s+/i) { indices << T.must(Regexp.last_match).begin(0) }
-      return [] if indices.empty?
+      each_auth_scheme_index(header) do |index, scheme|
+        indices << index if scheme.casecmp("Payment").zero?
+      end
+      indices
+    end
+
+    def self.next_auth_scheme_index(header, offset)
+      each_auth_scheme_index(header, offset) do |index, _scheme|
+        return index
+      end
+      nil
+    end
+
+    def self.each_auth_scheme_index(header, offset = 0)
+      in_quote = T.let(false, T::Boolean)
+      escaped = T.let(false, T::Boolean)
+      i = offset
+
+      while i < header.length
+        char = T.must(header[i])
+
+        if in_quote
+          if escaped
+            escaped = false
+          elsif char == "\\"
+            escaped = true
+          elsif char == "\""
+            in_quote = false
+          end
+          i += 1
+          next
+        end
+
+        if char == "\""
+          in_quote = true
+          i += 1
+          next
+        end
 
-      indices.each_with_index.map do |start_idx, i|
-        end_idx = (i + 1 < indices.length) ? indices[i + 1] : header.length
-        chunk = T.must(header[start_idx...end_idx]).sub(/,\s*$/, "")
-        from_www_authenticate(chunk)
+        if scheme_boundary?(header, i)
+          match = T.must(header[i..]).match(/\A([A-Za-z][A-Za-z0-9._~+\/-]*)\s+/)
+          # An auth-param permits OWS around "=" (key\s*=\s*value), so a token
+          # followed by whitespace then "=" is a parameter, not a new scheme.
+          if match && header[i + T.must(match[0]).length] != "="
+            yield i, T.must(match[1])
+            i += T.must(match[0]).length
+            next
+          end
+        end
+
+        i += 1
       end
     end
 
+    def self.scheme_boundary?(header, index)
+      previous = T.must(header[0...index]).rstrip
+      # Start of the header, including the case where only optional whitespace
+      # (RFC 9110 OWS) precedes the first scheme; otherwise a scheme is a
+      # boundary only immediately after a comma separating two schemes.
+      return true if previous.empty?
+
+      previous.end_with?(",")
+    end
+
     # Serialize to a WWW-Authenticate header value.
     def to_www_authenticate(realm)
       Mpp::Parsing.format_www_authenticate(self, realm)

data/lib/mpp/client/transport.rb

@@ -18,9 +18,35 @@ module Mpp
     class Transport
       extend T::Sig
 
-      sig { params(methods: T::Array[T.untyped]).void }
-      def initialize(methods:)
+      sig { params(methods: T::Array[T.untyped], events: T.nilable(Mpp::Events::Dispatcher)).void }
+      def initialize(methods:, events: nil)
         @methods = T.let(methods.to_h { |m| [m.name, m] }, T::Hash[String, T.untyped])
+        @events = T.let(events || Mpp::Events.client_dispatcher, Mpp::Events::Dispatcher)
+      end
+
+      sig { params(name: String, handler: T.untyped, block: T.nilable(T.proc.params(payload: T.untyped).returns(T.untyped))).returns(T.proc.void) }
+      def on(name, handler = nil, &block)
+        @events.on(name, handler, &block)
+      end
+
+      sig { params(handler: T.untyped, block: T.nilable(T.proc.params(payload: T.untyped).returns(T.untyped))).returns(T.proc.void) }
+      def on_challenge_received(handler = nil, &block)
+        on(Mpp::Events::CHALLENGE_RECEIVED, handler, &block)
+      end
+
+      sig { params(handler: T.untyped, block: T.nilable(T.proc.params(payload: T.untyped).returns(T.untyped))).returns(T.proc.void) }
+      def on_credential_created(handler = nil, &block)
+        on(Mpp::Events::CREDENTIAL_CREATED, handler, &block)
+      end
+
+      sig { params(handler: T.untyped, block: T.nilable(T.proc.params(payload: T.untyped).returns(T.untyped))).returns(T.proc.void) }
+      def on_payment_failed(handler = nil, &block)
+        on(Mpp::Events::PAYMENT_FAILED, handler, &block)
+      end
+
+      sig { params(handler: T.untyped, block: T.nilable(T.proc.params(payload: T.untyped).returns(T.untyped))).returns(T.proc.void) }
+      def on_payment_response(handler = nil, &block)
+        on(Mpp::Events::PAYMENT_RESPONSE, handler, &block)
       end
 
       # Send an HTTP request with automatic 402 payment handling.
@@ -34,7 +60,7 @@ module Mpp
 
         # Parse WWW-Authenticate headers
         www_auth_headers = response.get_fields("www-authenticate") || []
-        challenge, matched_method = find_matching_challenge(www_auth_headers)
+        challenge, matched_method = find_matching_challenge(www_auth_headers, input: url, response: response)
         return response unless challenge && matched_method
 
         # Check expiry before paying (client-side guardrail)
@@ -47,11 +73,90 @@ module Mpp
           end
         end
 
-        credential = matched_method.create_credential(challenge)
-        auth_header = credential.to_authorization
+        auth_header = T.let(nil, T.nilable(String))
+        create_credential = Kernel.lambda do
+          auth_header ||= credential_authorization(matched_method.create_credential(challenge))
+        end
+
+        begin
+          event_credential = nil
+          if @events.has_handlers?(Mpp::Events::CHALLENGE_RECEIVED)
+            # challenge.received can override credential creation; first non-empty credential wins.
+            event_credential = @events.emit_first(Mpp::Events::CHALLENGE_RECEIVED, {
+              challenge: challenge,
+              challenges: [challenge],
+              create_credential: create_credential,
+              input: url,
+              method: matched_method,
+              response: response
+            })
+          end
+          auth_header = credential_authorization(event_credential) unless event_credential.nil?
+          auth_header ||= create_credential.call
+
+          if @events.has_handlers?(Mpp::Events::CREDENTIAL_CREATED)
+            @events.emit(Mpp::Events::CREDENTIAL_CREATED, {
+              challenge: challenge,
+              credential: auth_header,
+              input: url,
+              method: matched_method,
+              response: response
+            })
+          end
+        rescue => e
+          if @events.has_handlers?(Mpp::Events::PAYMENT_FAILED)
+            @events.emit(Mpp::Events::PAYMENT_FAILED, {
+              challenge: challenge,
+              challenges: [challenge],
+              error: e,
+              input: url,
+              method: matched_method,
+              response: response
+            })
+          end
+          raise
+        end
 
         retry_headers = headers.merge("Authorization" => auth_header)
-        send_request(uri, method, retry_headers, body)
+        payment_response = nil
+        begin
+          payment_response = send_request(uri, method, retry_headers, body)
+        rescue => e
+          if @events.has_handlers?(Mpp::Events::PAYMENT_FAILED)
+            @events.emit(Mpp::Events::PAYMENT_FAILED, {
+              challenge: challenge,
+              challenges: [challenge],
+              credential: auth_header,
+              error: e,
+              input: url,
+              method: matched_method,
+              response: response
+            })
+          end
+          raise
+        end
+
+        if payment_response.code.to_i.between?(200, 299) && @events.has_handlers?(Mpp::Events::PAYMENT_RESPONSE)
+          @events.emit(Mpp::Events::PAYMENT_RESPONSE, {
+            challenge: challenge,
+            credential: auth_header,
+            input: url,
+            method: matched_method,
+            response: payment_response
+          })
+        elsif @events.has_handlers?(Mpp::Events::PAYMENT_FAILED)
+          @events.emit(Mpp::Events::PAYMENT_FAILED, {
+            challenge: challenge,
+            challenges: [challenge],
+            credential: auth_header,
+            error: Mpp::VerificationFailedError.new(reason: "retry returned HTTP #{payment_response.code}"),
+            input: url,
+            method: matched_method,
+            response: payment_response
+          })
+        end
+
+        payment_response
       end
 
       sig { params(url: T.any(URI::Generic, String), kwargs: T.untyped).returns(T.untyped) }
@@ -97,20 +202,51 @@ module Mpp
         http.request(req)
       end
 
-      sig { params(www_auth_headers: T.untyped).returns(T::Array[T.untyped]) }
-      def find_matching_challenge(www_auth_headers)
+      sig { params(www_auth_headers: T.untyped, input: T.untyped, response: T.untyped).returns(T::Array[T.untyped]) }
+      def find_matching_challenge(www_auth_headers, input: nil, response: nil)
         www_auth_headers.each do |header|
-          next unless header.downcase.start_with?("payment ")
-
-          begin
-            parsed = Mpp::Challenge.from_www_authenticate(header)
+          Mpp::Challenge.www_authenticate_chunks(header).each do |chunk|
+            parsed = Mpp::Challenge.from_www_authenticate(chunk)
             return [parsed, @methods[parsed.method]] if @methods.key?(parsed.method)
-          rescue Mpp::ParseError
+          rescue Mpp::ParseError => e
+            # Skip a malformed challenge but keep scanning the rest: a bad chunk
+            # earlier in a merged value must not hide a supported challenge that
+            # follows it.
+            if @events.has_handlers?(Mpp::Events::PAYMENT_FAILED)
+              @events.emit(Mpp::Events::PAYMENT_FAILED, {
+                error: e,
+                input: input,
+                response: response
+              })
+            end
             next
           end
         end
         [nil, nil]
       end
+
+      sig { params(credential: T.untyped).returns(String) }
+      def credential_authorization(credential)
+        auth_header = if credential.respond_to?(:to_authorization)
+          credential.to_authorization
+        elsif credential.is_a?(String)
+          credential
+        else
+          raise ArgumentError, "Credential must be a String or respond to #to_authorization"
+        end
+
+        validate_authorization_header(auth_header)
+        auth_header
+      end
+
+      sig { params(auth_header: String).void }
+      def validate_authorization_header(auth_header)
+        unless auth_header.start_with?("Payment ") && auth_header.length > 8
+          raise ArgumentError, "Credential must be a non-empty Payment authorization header"
+        end
+
+        raise ArgumentError, "Credential contains invalid header characters" if auth_header.match?(/[[:cntrl:]]/)
+      end
     end
 
     # Module-level convenience methods
@@ -118,20 +254,20 @@ module Mpp
 
     module_function
 
-    sig { params(method: T.untyped, url: T.untyped, methods: T::Array[T.untyped], kwargs: T.untyped).returns(T.untyped) }
-    def request(method, url, methods:, **kwargs)
-      transport = Transport.new(methods: methods)
+    sig { params(method: T.untyped, url: T.untyped, methods: T::Array[T.untyped], events: T.nilable(Mpp::Events::Dispatcher), kwargs: T.untyped).returns(T.untyped) }
+    def request(method, url, methods:, events: nil, **kwargs)
+      transport = Transport.new(methods: methods, events: events)
       transport.request(method, url, **kwargs)
     end
 
-    sig { params(url: T.untyped, methods: T::Array[T.untyped], kwargs: T.untyped).returns(T.untyped) }
-    def get(url, methods:, **kwargs)
-      request("GET", url, **T.unsafe({methods: methods, **kwargs}))
+    sig { params(url: T.untyped, methods: T::Array[T.untyped], events: T.nilable(Mpp::Events::Dispatcher), kwargs: T.untyped).returns(T.untyped) }
+    def get(url, methods:, events: nil, **kwargs)
+      request("GET", url, **T.unsafe({methods: methods, events: events, **kwargs}))
     end
 
-    sig { params(url: T.untyped, methods: T::Array[T.untyped], kwargs: T.untyped).returns(T.untyped) }
-    def post(url, methods:, **kwargs)
-      request("POST", url, **T.unsafe({methods: methods, **kwargs}))
+    sig { params(url: T.untyped, methods: T::Array[T.untyped], events: T.nilable(Mpp::Events::Dispatcher), kwargs: T.untyped).returns(T.untyped) }
+    def post(url, methods:, events: nil, **kwargs)
+      request("POST", url, **T.unsafe({methods: methods, events: events, **kwargs}))
     end
   end
 end

data/lib/mpp/errors.rb

@@ -10,6 +10,9 @@ module Mpp
   # Base verification error.
   class VerificationError < StandardError; end
 
+  # Retryable verification error for transactions that were accepted but not mined yet.
+  class TransactionPendingError < VerificationError; end
+
   # Base class for all payment-related errors with RFC 9457 support.
   class PaymentError < StandardError
     extend T::Sig

data/lib/mpp/events.rb

@@ -0,0 +1,124 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Events
+    extend T::Sig
+
+    ANY = "*"
+    CHALLENGE_CREATED = "challenge.created"
+    CHALLENGE_RECEIVED = "challenge.received"
+    CREDENTIAL_CREATED = "credential.created"
+    PAYMENT_FAILED = "payment.failed"
+    PAYMENT_RESPONSE = "payment.response"
+    PAYMENT_SUCCESS = "payment.success"
+
+    class Event < T::Struct
+      const :name, String
+      const :payload, T::Hash[Symbol, T.untyped]
+    end
+
+    class Dispatcher
+      extend T::Sig
+
+      sig { params(event_names: T::Array[String]).void }
+      def initialize(event_names:)
+        @event_names = T.let(event_names.to_h { |name| [name, true] }, T::Hash[String, T::Boolean])
+        @event_names[ANY] = true
+        @handlers = T.let(@event_names.keys.to_h { |name| [name, []] }, T::Hash[String, T::Array[T.untyped]])
+      end
+
+      sig { params(name: String, handler: T.untyped, block: T.nilable(T.proc.params(payload: T.untyped).returns(T.untyped))).returns(T.proc.void) }
+      def on(name, handler = nil, &block)
+        raise ArgumentError, "Unknown event: #{name}" unless @event_names.key?(name)
+
+        callback = handler || block
+        raise ArgumentError, "handler is required" unless callback
+
+        handlers = T.must(@handlers[name])
+        handlers << callback
+        Kernel.lambda { handlers.delete(callback) }
+      end
+
+      sig { params(name: String, payload: T::Hash[Symbol, T.untyped]).void }
+      def emit(name, payload)
+        return unless has_handlers?(name)
+
+        emit_observers(name, payload)
+        emit_any(name, payload)
+      end
+
+      sig { params(name: String, payload: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
+      def emit_first(name, payload)
+        return nil unless has_handlers?(name)
+
+        result = T.let(nil, T.untyped)
+
+        T.must(@handlers[name]).each do |handler|
+          value = call(handler, payload)
+          next if empty_result?(value)
+
+          result = value
+          break
+        end
+
+        emit_any(name, payload)
+        result
+      end
+
+      sig { params(name: T.nilable(String)).returns(T::Boolean) }
+      def has_handlers?(name = nil)
+        return @handlers.any? { |_event_name, handlers| !handlers.empty? } unless name
+
+        !T.must(@handlers[name]).empty? || !T.must(@handlers[ANY]).empty?
+      end
+
+      private
+
+      sig { params(name: String, payload: T::Hash[Symbol, T.untyped]).void }
+      def emit_observers(name, payload)
+        T.must(@handlers[name]).each { |handler| call(handler, payload) }
+      end
+
+      sig { params(name: String, payload: T::Hash[Symbol, T.untyped]).void }
+      def emit_any(name, payload)
+        any_handlers = T.must(@handlers[ANY])
+        return if any_handlers.empty?
+
+        event = Event.new(name: name, payload: payload)
+        any_handlers.each { |handler| call(handler, event) }
+      end
+
+      sig { params(handler: T.untyped, payload: T.untyped).returns(T.untyped) }
+      def call(handler, payload)
+        handler.call(payload)
+      rescue
+        nil
+      end
+
+      sig { params(value: T.untyped).returns(T::Boolean) }
+      def empty_result?(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?)
+      end
+    end
+
+    sig { returns(Dispatcher) }
+    def self.client_dispatcher
+      Dispatcher.new(event_names: [
+        CHALLENGE_RECEIVED,
+        CREDENTIAL_CREATED,
+        PAYMENT_FAILED,
+        PAYMENT_RESPONSE
+      ])
+    end
+
+    sig { returns(Dispatcher) }
+    def self.server_dispatcher
+      Dispatcher.new(event_names: [
+        CHALLENGE_CREATED,
+        PAYMENT_FAILED,
+        PAYMENT_SUCCESS
+      ])
+    end
+  end
+end

data/lib/mpp/extensions/mcp/types.rb

@@ -182,7 +182,8 @@ module Mpp
           Mpp::Receipt.new(
             status: status,
             timestamp: Time.iso8601(timestamp.gsub("Z", "+00:00")),
-            reference: reference || ""
+            reference: reference || "",
+            method: method
           )
         end
 

data/lib/mpp/methods/stripe/charge_intent.rb

@@ -11,10 +11,11 @@ module Mpp
       class ChargeIntent
         attr_reader :name
 
-        def initialize(secret_key:, api_base: Defaults::STRIPE_API_BASE)
+        def initialize(secret_key:, api_base: Defaults::STRIPE_API_BASE, client: nil)
           @name = "charge"
           @secret_key = secret_key
           @api_base = api_base
+          @client = client
         end
 
         def verify(credential, request)
@@ -31,7 +32,25 @@ module Mpp
           end
 
           spt = payload_data["spt"]
-          external_id = payload_data["externalId"]
+          credential_external_id = payload_data["externalId"]
+          request_external_id = request["externalId"]
+          if !request_external_id.nil? && credential_external_id != request_external_id
+            raise Mpp::InvalidChallengeError.new(
+              challenge_id: credential.challenge.id,
+              reason: "credential externalId does not match request externalId"
+            )
+          end
+
+          method_details = request["methodDetails"]
+          method_details = {} unless method_details.is_a?(Hash)
+
+          # Enforce the payment method types allowlist from the challenge
+          payment_method_types = method_details["paymentMethodTypes"]
+          unless payment_method_types.is_a?(Array) &&
+              payment_method_types.any? &&
+              payment_method_types.all? { |type| type.is_a?(String) && !type.strip.empty? }
+            raise Mpp::VerificationError, "Invalid or missing methodDetails.paymentMethodTypes"
+          end
 
           # Build PaymentIntent params
           params = {
@@ -39,28 +58,28 @@ module Mpp
             currency: request["currency"],
             shared_payment_granted_token: spt,
             confirm: true,
-            automatic_payment_methods: {
-              enabled: true,
-              allow_redirects: "never"
-            }
+            payment_method_types: payment_method_types
           }
 
           # Include metadata from methodDetails if present
-          method_details = request["methodDetails"]
-          if method_details.is_a?(Hash) && method_details["metadata"].is_a?(Hash)
+          if method_details["metadata"].is_a?(Hash)
             params[:metadata] = method_details["metadata"].transform_values(&:to_s)
           end
 
-          # Create PaymentIntent via Stripe SDK
-          begin
-            Kernel.require "stripe"
-          rescue LoadError
-            raise "stripe gem is required for Stripe charge verification. Install with: gem install stripe"
+          unless @client
+            begin
+              Kernel.require "stripe"
+            rescue LoadError
+              raise "stripe gem is required for Stripe charge verification. Install with: gem install stripe"
+            end
           end
 
           begin
-            client = ::Stripe::StripeClient.new(@secret_key)
-            result = client.v1.payment_intents.create(params)
+            client = @client || ::Stripe::StripeClient.new(@secret_key)
+            result = client.v1.payment_intents.create(
+              params,
+              {idempotency_key: stripe_idempotency_key(credential)}
+            )
           rescue => e
             raise Mpp::VerificationError, e.message
           end
@@ -82,7 +101,13 @@ module Mpp
             raise Mpp::VerificationError, "PaymentIntent #{pi_id} has status: #{status}"
           end
 
-          Mpp::Receipt.success(pi_id, method: "stripe", external_id: external_id)
+          Mpp::Receipt.success(pi_id, method: "stripe", external_id: request_external_id)
+        end
+
+        private
+
+        def stripe_idempotency_key(credential)
+          "mpp-stripe-charge-#{credential.challenge.id}"
         end
       end
     end

data/lib/mpp/methods/stripe/client_method.rb

@@ -29,7 +29,11 @@ module Mpp
           )
 
           payload = {"spt" => spt_id}
-          payload["externalId"] = @external_id if @external_id
+          request_external_id = request["externalId"]
+          payload["externalId"] = request_external_id if request_external_id.is_a?(String)
+          if @external_id && !payload.key?("externalId")
+            raise ArgumentError, "external_id must be bound by the challenge request"
+          end
 
           Mpp::Credential.new(
             challenge: challenge.to_echo,