Added Payment Feedback API

Author: ooi2018

docs/source/code.md

@@ -14,7 +14,7 @@ Retrieve an existing transaction from FraudLabs Pro fraud detection system.
 
 | Parameter Name | Parameter Type | Description                                                  |
 | -------------- | -------------- | ------------------------------------------------------------ |
-| id            | string         | FraudLabs Pro transaction ID or Order ID.                    |
+| id             | string         | FraudLabs Pro transaction ID or Order ID.                    |
 
 :return: Returns the details about the transaction in JSON object.
 :rtype: Object
@@ -85,9 +85,9 @@ Approve, reject or ignore a transaction.
 
 | Parameter    | Type    | Description |
 |--------------|---------|---------------------|
-| id          | string  | (required) Unique transaction Id generated by Fraud Check API. |
-| action         | string  | (required) Perform APPROVE, REJECT, or REJECT_BLACKLIST action to transaction.<br/>• APPROVE: Approve a transaction<br/>• REJECT: Reject a transaction<br/>• REJECT_BLACKLIST: Reject and blacklist the transaction<br/>When a transaction was blacklisted, the information will be recorded into the system for future blacklist validation check. |
-| note  | integer | (optional) Notes for the feedback request. |
+| id           | string  | (required) Unique transaction Id generated by Fraud Check API. |
+| action       | string  | (required) Perform APPROVE, REJECT, or REJECT_BLACKLIST action to transaction.<br/>• APPROVE: Approve a transaction<br/>• REJECT: Reject a transaction<br/>• REJECT_BLACKLIST: Reject and blacklist the transaction<br/>When a transaction was blacklisted, the information will be recorded into the system for future blacklist validation check. |
+| note         | integer | (optional) Notes for the feedback request. |
 ```
 
 ```{py:function} validate(params)
@@ -104,6 +104,7 @@ Retrieve geolocation information for an IP address.
 | billing->password    | string | (optional) User's password.                                             |
 | billing->email       | string | (optional) User's email address.                                        |
 | billing->phone       | string | (optional) User's phone number.                                         |
+| billing->billto       | string  | (optional) Billing details such as company name. |
 | billing->address       | string  | (optional) Street address of billing address. |
 | billing->city       | string  | (optional) City of billing address. |
 | billing->state      | string  | (optional) State of billing address. It supports state codes, e.g. NY (New York), for state or province of United States or Canada.|
@@ -195,7 +196,7 @@ Retrieve geolocation information for an IP address.
 
 ## SMSVerification Class
 ```{py:class} SMSVerification(api_key)
-Initiate FraudValidation class with FraudLabs Pro API key.
+Initiate SMSVerification class with FraudLabs Pro API key.
 
 :param str api_key: (Required) FraudLabs Pro API key.
 ```
@@ -231,12 +232,40 @@ Get SMS Verification result.
 | Parameter         | Type   | Description |
 |-------------------|--------|-------------|
 | tran_id           | string | (required) Unique ID (20 characters) for this particular API call. |
-| otp | string | (required) The OTP that was sent to the recipient’s phone. |
+| otp               | string | (required) The OTP that was sent to the recipient’s phone. |
 
 :return: Returns the details about the transaction in JSON object.
 :rtype: Object
 
 | Parameter         | Type   | Description |
 |-------------------|--------|-------------|
-| result           | string | Indicates if the input parameters matched a valid OTP. Y if a valid OTP is found and N if no valid OTP found. |
+| result            | string | Indicates if the input parameters matched a valid OTP. Y if a valid OTP is found and N if no valid OTP found. |
+```
+
+## Payment Class
+```{py:class} Payment(api_key)
+Initiate Payment class with FraudLabs Pro API key.
+
+:param str api_key: (Required) FraudLabs Pro API key.
+```
+
+```{py:function} feedback(params)
+Report the final payment status back to the system.
+
+:param array params: (Required) The parameters of order details.
+
+| Parameter        | Type    | Description |
+|------------------|---------|---------------------|
+| email            | string  | (required) Email address of the payment order. |
+| status           | string  | (required) Status of the payment order. |
+| message          | string  | (required) Message returned from the payment gateway for the payment order. |
+| fraudlabspro_id  | string  | (optional) Unique transaction Id generated by Fraud Check API. |
+
+
+:return: Returns the details about the transaction in map object.
+:rtype: Object
+
+| Parameter         | Type   | Description |
+|-------------------|--------|-------------|
+| result           | string | Indicates if submission is successful. |
 ```

docs/source/quickstart.md

@@ -19,14 +19,14 @@ pip install fraudlabspro-python
 You can validate your order as below:
 
 ```python
- # import SDK to use the function
+# import SDK to use the function
 from fraudlabspro.fraudvalidation import FraudValidation
 
- # Configure your API key
+# Configure your API key
 api_key = 'YOUR_API_KEY'
 fraud_validation = FraudValidation(api_key)
 
- # Order Details
+# Order Details
 dict1 = {
 	'ip': '146.112.62.105',
 	'order': {
@@ -62,7 +62,7 @@ dict1 = {
 	}
 }
 
- # Sends the order details to FraudLabs Pro
+# Sends the order details to FraudLabs Pro
 result = fraud_validation.validate(dict1)
 ```
 
@@ -71,35 +71,35 @@ result = fraud_validation.validate(dict1)
 You can get the details of a transaction as below:
 
 ```python
- # import SDK to use the function
+# import SDK to use the function
 from fraudlabspro.fraudvalidation import FraudValidation
 
- # Configure your API key
+# Configure your API key
 api_key = 'YOUR_API_KEY'
 fraud_validation = FraudValidation(api_key)
 
- # Values to get transaction details
+# Values to get transaction details
 get_transaction_variables = {
 	'id': '20180705-WISXW2',
 }
 
- # Send the values to FraudLabs Pro
+# Send the values to FraudLabs Pro
 result = fraud_validation.get_transaction(get_transaction_variables)
 ```
 
-### Feedback
+### Feedback an order
 
 You can approve, reject or ignore a transaction as below:
 
 ```python
  # import SDK to use the function
 from fraudlabspro.fraudvalidation import FraudValidation
 
- # Configure your API key
+# Configure your API key
 api_key = 'YOUR_API_KEY'
 fraud_validation = FraudValidation(api_key)
 
- # Set feedback of the particular order
+# Set feedback of the particular order
 feedback_variables = {
 	'id': '20180705-WISXW2',
 	# Three actions available: APPROVE, REJECT, REJECT_BLACKLIST
@@ -118,11 +118,11 @@ You can send SMS verification for authentication purpose as below:
  # import SDK to use the function
 from fraudlabspro.smsverification import SMSVerification
 
- # Configure your API key
+# Configure your API key
 api_key = 'YOUR_API_KEY'
 sms_validation = SMSVerification(api_key)
 
- # Send SMS verification
+# Send SMS verification
 sms_verification_variables = {
 	'tel': '+123456789',
 	'country_code': 'US',
@@ -137,17 +137,41 @@ result = sms_validation.send_sms(sms_verification_variables)
 You can verify the OTP sent by Fraudlabs Pro SMS verification API as below:
 
 ```python
- # import SDK to use the function
+# import SDK to use the function
 from fraudlabspro.smsverification import SMSVerification
 
  # Configure your API key
 api_key = 'YOUR_API_KEY'
 sms_validation = SMSVerification(api_key)
 
- # Get SMS verification result
+# Get SMS verification result
 verify_sms_variables = {
 	'tran_id': 'UNIQUE_TRANS_ID',
 	'otp': 'OTP_RECEIVED',
 }
 result = sms_validation.verify_sms(verify_sms_variables)
+```
+
+### Report Payment Gateway Feedback
+
+You can report payment gateway feedback as below:
+
+```python
+# import SDK to use the function
+from fraudlabspro.payment import Payment
+
+# Configure your API key
+api_key = 'YOUR_API_KEY'
+payment_cls = Payment(api_key)
+
+# Set feedback of the particular order
+feedback_variables = {
+	'email': 'aaa@mailinator.com',
+    'status': '-',
+    'message': 'This is a test.'
+}
+
+result = payment_cls.feedback(feedback_variables)
+
+print(result)
 ```

example.py

@@ -1,12 +1,11 @@
 # import SDK to use the function
 from fraudlabspro.fraudvalidation import FraudValidation
 from fraudlabspro.smsverification import SMSVerification
+from fraudlabspro.payment import Payment
 
  # Configure your API key
 api_key = 'YOUR_API_KEY'
 
-# validation = fraudlabspro.fraudvalidation.FraudValidation(api_key)
-# validation = fraudlabspro.FraudValidation(api_key)
 fraud_validation = FraudValidation(api_key)
 
 """
@@ -94,4 +93,17 @@
 }
 print(sms_validation.verify_sms(verify_sms_variables))
 
+payment_cls = Payment(api_key)
 
+"""
+ # Here is example of report the final payment status of an order.
+"""
+feedback_variables = {
+	'email': 'aaa@mailinator.com',
+    'status': '-',
+    'message': 'This is a test.'
+}
+
+result = payment_cls.feedback(feedback_variables)
+
+print(result)

fraudlabspro/constants.py

@@ -0,0 +1,4 @@
+# Constants that will be use across various classes
+
+BASE_URL = 'https://api.fraudlabspro.com/v2/'
+MODULE_VERSION = '3.1.0'

fraudlabspro/fraudvalidation.py

@@ -171,6 +171,10 @@ def validate(self, dictionary):
                     user_phone = re.sub(r'\D','',phone)
             else:
                 user_phone = ''
+            if 'billto' in dictionary['billing']:
+                bill_to = dictionary['billing']['billto']
+            else:
+                bill_to = ''
             if 'address' in dictionary['billing']:
                 bill_addr = dictionary['billing']['address']
             else:
@@ -200,6 +204,7 @@ def validate(self, dictionary):
             email_domain = ''
             email_hash = ''
             user_phone = ''
+            bill_to = ''
             bill_addr = ''
             bill_city = ''
             bill_state = ''
@@ -274,6 +279,7 @@ def validate(self, dictionary):
                     'email_hash': email_hash,
                     'email_domain': email_domain,
                     'user_phone': user_phone,
+                    'bill_to': bill_to,
                     'bill_addr': bill_addr,
                     'bill_city': bill_city,
                     'bill_state': bill_state,

fraudlabspro/payment.py

@@ -0,0 +1,54 @@
+import json
+import urllib.parse
+import urllib.request
+from urllib.parse import urljoin
+
+from .constants import BASE_URL, MODULE_VERSION
+
+
+class Payment:
+    """
+    FraudLabsPro Payment module.
+
+    Allows merchants to report the final payment status back to the system,
+    helping improve fraud detection and risk assessment.
+    """
+
+    def __init__(self, api_key):
+        self.api_key = api_key
+
+    def feedback(self, feedback_variables):
+        # Validate required fields
+        required_fields = ['email', 'status', 'message']
+        for field in required_fields:
+            if field not in feedback_variables:
+                return json.dumps({"error": f"{field} is required"})
+
+        # Prepare payload
+        payload = {
+            'key': self.api_key,
+            'source_version': MODULE_VERSION,
+            'email': feedback_variables['email'],
+            'status': feedback_variables['status'],
+            'message': feedback_variables['message'],
+        }
+
+        # Handle optional fraudlabspro_id
+        if 'fraudlabspro_id' in feedback_variables:
+            payload['id'] = feedback_variables['fraudlabspro_id']
+
+        url = urljoin(BASE_URL, 'payment/feedback')
+        data = urllib.parse.urlencode(payload).encode('utf-8')
+
+        try:
+            request = urllib.request.Request(url, data=data)
+            with urllib.request.urlopen(request) as response:
+                raw_data = response.read().decode('utf-8')
+            json_obj = json.loads(raw_data)
+        except urllib.error.HTTPError as http_error:
+            error_data = http_error.read().decode('utf-8')
+            json_obj = json.loads(error_data)
+        except Exception as e:
+            return json.dumps({"error": str(e)})
+
+        return json.dumps(json_obj, indent=4)

setup.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
 	name="fraudlabspro-python",
-	version="3.0.3",
+	version="3.1.0",
 	author="FraudLabs Pro",
 	author_email="support@fraudlabspro.com",
 	description="A Python module enables user to easily implement fraud detection feature into their solution using the API from https://www.fraudlabspro.com.",