@@ -203,6 +203,7 @@
 * Stripe PI: Update API version [almalee24] #5360
 * Airwallex: Add optional products array field [yunnydang] #5530
 * Pin Payments: Add inquire method to get details of payment [hudakh] #5537
+* Pin Payments: Add transaction_search method and support paginated API responses [hudakh] #5541
 
 == Version 1.137.0 (August 2, 2024)
 * Unlock dependency on `rexml` to allow fixing a CVE (#5181).
 
@@ -374,6 +374,7 @@ Spreedly Core gateway (December 2012)
 Pin gateway (February 2013)
 
 * Myles Eftos (madpilot)
+* Portions of the Pin Payments Gateway by Huda Kharrufa (hudakh)
 
 Merchant Warrior (February 2013)
 
 
@@ -89,6 +89,29 @@ def inquire(token, options = {})
         commit(:get, "charges/#{CGI.escape(token)}", nil, options)
       end
 
+      # Returns a paginated list of charges matching the search criteria.
+      # ==== Options:
+      # * <tt>:query </tt> -- (Optional) Return only charges whose fields match the query. Fields covered include description, email, metadata, cardholder name, currency, amount (exact), charge token (exact), card token (exact), refund token (exact), and customer token (exact).
+      # * <tt>:start_date </tt> -- (Optional) Return only charges created on or after this date (e.g. 2012/12/25).
+      # * <tt>:end_date </tt> -- (Optional) Return only charges created before this date (e.g. 2013/12/25).
+      # * <tt>:sort</tt> -- (Optional) The field used to sort the charges (created_at or amount). Default value is created_at.
+      # * <tt>:direction </tt> -- (Optional) The direction in which to sort the charges (1 for ascending or -1 for descending). Default value is 1.
+      #
+      def transaction_search(options = {})
+        params = {}
+        params[:query] = options[:query] if options[:query]
+        params[:start_date] = options[:start_date] if options[:start_date]
+        params[:end_date] = options[:end_date] if options[:end_date]
+        params[:sort] = options[:sort] if options[:sort]
+        params[:direction] = options[:direction] if options[:direction]
+        params[:page] = options[:page] if options[:page]
+
+        action = 'charges/search'
+        action += '?' + params.to_query unless params.empty?
+
+        commit(:get, action, nil, options)
+      end
+
       # Verify a previously authorized charge.
       def verify_3ds(session_token, options = {})
         commit(:get, "/charges/verify?session_token=#{session_token}", nil, options)
@@ -257,6 +280,8 @@ def commit(method, action, params, options)
 
         if body.nil?
           no_content_response
+        elsif body['response'].is_a?(Array)
+          paginated_response(body)
         elsif body['response']
           success_response(body)
         elsif body['error']
@@ -302,6 +327,15 @@ def unparsable_response(raw_response)
         return Response.new(false, message)
       end
 
+      def paginated_response(body)
+        Response.new(
+          true,
+          'Search successful',
+          body,
+          test: test?
+        )
+      end
+
       def token(response)
         if response['token'].start_with?('cus')
           "#{response.dig('card', 'token')};#{response['token']}"
 
@@ -289,6 +289,99 @@ def test_successful_inquire
     assert_success inquire
   end
 
+  def test_successful_transaction_search
+    response = @gateway.transaction_search
+    assert_success response
+    assert response.params['response'].is_a?(Array)
+    assert response.params.key?('pagination')
+  end
+
+  def test_transaction_search_with_query
+    response = @gateway.transaction_search(query: @options[:email])
+    assert_success response
+    assert response.params['response'].is_a?(Array)
+  end
+
+  def test_transaction_search_with_date_range
+    today = Date.today
+    start_date = (today - 30).strftime('%Y-%m-%d')
+    end_date = today.strftime('%Y-%m-%d')
+
+    response = @gateway.transaction_search(start_date: start_date, end_date: end_date)
+    assert_success response
+    assert response.params['response'].is_a?(Array)
+
+    # Verify all returned transactions are within the date range
+    response.params['response'].each do |charge|
+      charge_date = Date.parse(charge['created_at'])
+      assert charge_date >= Date.parse(start_date), "Charge date should be on or after start date"
+      assert charge_date <= Date.parse(end_date), "Charge date should be on or before end date"
+    end
+  end
+
+  def test_transaction_search_with_pagination
+    response = @gateway.transaction_search(page: 1)
+    assert_success response
+    assert_equal 1, response.params['pagination']['current']
+    assert response.params['pagination'].key?('per_page')
+    assert response.params['pagination'].key?('count')
+  end
+
+  def test_transaction_search_with_sort_ascending
+    response = @gateway.transaction_search(sort: 'created_at', direction: 1)
+    assert_success response
+
+    if response.params['response'].length > 1
+      # Verify ascending order
+      dates = response.params['response'].map { |charge| Time.parse(charge['created_at']) }
+      assert_equal dates, dates.sort, "Results should be sorted in ascending order by created_at"
+    end
+  end
+
+  def test_transaction_search_with_sort_descending
+    response = @gateway.transaction_search(sort: 'created_at', direction: -1)
+    assert_success response
+
+    if response.params['response'].length > 1
+      # Verify descending order
+      dates = response.params['response'].map { |charge| Time.parse(charge['created_at']) }
+      assert_equal dates, dates.sort.reverse, "Results should be sorted in descending order by created_at"
+    end
+  end
+
+  def test_transaction_search_with_amount_sort
+    response = @gateway.transaction_search(sort: 'amount', direction: -1)
+    assert_success response
+
+    if response.params['response'].length > 1
+      # Verify descending order by amount
+      amounts = response.params['response'].map { |charge| charge['amount'] }
+      assert_equal amounts, amounts.sort.reverse, "Results should be sorted in descending order by amount"
+    end
+  end
+
+  def test_transaction_search_with_multiple_filters
+    today = Date.today
+    start_date = (today - 7).strftime('%Y/%m/%d')
+
+    response = @gateway.transaction_search(
+      query: @options[:email],
+      start_date: start_date,
+      sort: 'created_at',
+      direction: -1
+    )
+
+    assert_success response
+    assert response.params['response'].is_a?(Array)
+  end
+
+  def test_transaction_search_empty_results
+    # Search with a very specific query that shouldn't match anything
+    response = @gateway.transaction_search(query: 'nonexistent-email-xyz@test.invalid')
+    assert_success response
+    assert_equal 0, response.params['response'].length
+  end
+
   def test_invalid_login
     gateway = PinGateway.new(api_key: '')
     response = gateway.purchase(@amount, @credit_card, @options)
 
@@ -253,6 +253,77 @@ def test_successful_inquire
     assert response.test?
   end
 
+  def test_successful_transaction_search
+    @gateway.expects(:ssl_request).with(:get, 'https://test-api.pinpayments.com/1/charges/search', nil, instance_of(Hash)).returns(successful_transaction_search_response)
+
+    assert response = @gateway.transaction_search
+    assert_success response
+    assert_equal 2, response.params['response'].length
+    assert_equal 'ch_Kw_JxmVqMeSOQU19_krRdw', response.params['response'][0]['token']
+    assert response.test?
+  end
+
+  def test_transaction_search_with_query
+    @gateway.expects(:ssl_request).with(:get, 'https://test-api.pinpayments.com/1/charges/search?query=roland%40pinpayments.com', nil, instance_of(Hash)).returns(successful_transaction_search_response)
+
+    assert response = @gateway.transaction_search(query: 'roland@pinpayments.com')
+    assert_success response
+    assert_equal 2, response.params['response'].length
+    assert response.test?
+  end
+
+  def test_transaction_search_with_date_range
+    start_date = '2025-01-01'
+    end_date = '2025-01-31'
+    @gateway.expects(:ssl_request).with(:get, "https://test-api.pinpayments.com/1/charges/search?end_date=#{end_date}&start_date=#{start_date}", nil, instance_of(Hash)).returns(successful_transaction_search_response)
+
+    assert response = @gateway.transaction_search(start_date: start_date, end_date: end_date)
+    assert_success response
+    assert response.test?
+  end
+
+  def test_transaction_search_with_pagination
+    @gateway.expects(:ssl_request).with(:get, 'https://test-api.pinpayments.com/1/charges/search?page=2', nil, instance_of(Hash)).returns(successful_transaction_search_response)
+
+    assert response = @gateway.transaction_search(page: 2)
+    assert_success response
+    assert response.test?
+  end
+
+  def test_transaction_search_with_sort_and_direction
+    @gateway.expects(:ssl_request).with(:get, 'https://test-api.pinpayments.com/1/charges/search?direction=1&sort=created_at', nil, instance_of(Hash)).returns(successful_transaction_search_response)
+
+    assert response = @gateway.transaction_search(sort: 'created_at', direction: 1)
+    assert_success response
+    assert response.test?
+  end
+
+  def test_transaction_search_with_amount_sort
+    @gateway.expects(:ssl_request).with(:get, 'https://test-api.pinpayments.com/1/charges/search?direction=-1&sort=amount', nil, instance_of(Hash)).returns(successful_transaction_search_response)
+
+    assert response = @gateway.transaction_search(sort: 'amount', direction: -1)
+    assert_success response
+    assert response.test?
+  end
+
+  def test_transaction_search_empty_results
+    @gateway.expects(:ssl_request).with(:get, 'https://test-api.pinpayments.com/1/charges/search', nil, instance_of(Hash)).returns(empty_transaction_search_response)
+
+    assert response = @gateway.transaction_search
+    assert_success response
+    assert_equal 0, response.params['response'].length
+    assert response.test?
+  end
+
+  def test_unsuccessful_transaction_search
+    @gateway.expects(:ssl_request).returns(failed_transaction_search_response)
+
+    assert response = @gateway.transaction_search
+    assert_failure response
+    assert_equal 'The requested resource could not be found.', response.message
+    assert response.test?
+  end
+
   def test_successful_refund
     token = 'ch_encBuMDf17qTabmVjDsQlg'
     @gateway.expects(:ssl_request).with(:post, "https://test-api.pinpayments.com/1/charges/#{token}/refunds", { amount: '100' }.to_json, instance_of(Hash)).returns(successful_refund_response)
@@ -800,6 +871,96 @@ def successful_inquire_response
     }'
   end
 
+  def successful_transaction_search_response
+    '{
+      "response": [
+        {
+          "token": "ch_Kw_JxmVqMeSOQU19_krRdw",
+          "success": true,
+          "amount": 400,
+          "currency": "AUD",
+          "description": "test charge",
+          "email": "roland@pinpayments.com",
+          "ip_address": "203.192.1.172",
+          "created_at": "2025-01-14T03:00:41Z",
+          "status_message": "Success!",
+          "error_message": null,
+          "card": {
+            "token": "card_0oG1hjachN7g8KsOnWlOcg",
+            "display_number": "XXXX-XXXX-XXXX-0000",
+            "scheme": "master",
+            "address_line1": "42 Sevenoaks St",
+            "address_line2": null,
+            "address_city": "Lathlain",
+            "address_postcode": "6454",
+            "address_state": "WA",
+            "address_country": "AU"
+          },
+          "transfer": [],
+          "amount_refunded": 0,
+          "total_fees": 62,
+          "merchant_entitlement": 338,
+          "refund_pending": false,
+          "captured": true,
+          "captured_at": "2025-01-14T03:00:41Z"
+        },
+        {
+          "token": "ch_ABC123XYZ",
+          "success": true,
+          "amount": 200,
+          "currency": "AUD",
+          "description": "another test charge",
+          "email": "roland@pinpayments.com",
+          "ip_address": "203.192.1.173",
+          "created_at": "2025-01-15T04:00:41Z",
+          "status_message": "Success!",
+          "error_message": null,
+          "card": {
+            "token": "card_ABC123",
+            "display_number": "XXXX-XXXX-XXXX-1111",
+            "scheme": "visa"
+          },
+          "transfer": [],
+          "amount_refunded": 0,
+          "total_fees": 32,
+          "merchant_entitlement": 168,
+          "refund_pending": false,
+          "captured": true,
+          "captured_at": "2025-01-15T04:00:41Z"
+        }
+      ],
+      "pagination": {
+        "current": 1,
+        "previous": null,
+        "next": null,
+        "per_page": 25,
+        "pages": 1,
+        "count": 2
+      }
+    }'
+  end
+
+  def empty_transaction_search_response
+    '{
+      "response": [],
+      "pagination": {
+        "current": 1,
+        "previous": null,
+        "next": null,
+        "per_page": 25,
+        "pages": 0,
+        "count": 0
+      }
+    }'
+  end
+
+  def failed_transaction_search_response
+    '{
+      "error": "not_found",
+      "error_description": "The requested resource could not be found."
+    }'
+  end
+
   def successful_refund_response
     '{
       "response":{