feat(api)!: move to generic refund status API

The refund batch status API is at path `GET /refund/batch/{batchID}`,
which while continuing to work, will no longer return `batchID` as
part of the response. This allows the internal API to be more generic,
supporting fetching the refund status by more identifiers.

The path for the internal API has now changed to:
`GET /refund/{identifierType}/{identifierValue}`

The allowed values for `identifier_type` at this point are:
- batch
- bill

If you were not using the `batch_id` in the response in your code,
then your integration will continue to work. In either case, the
`get_batch_refund_status` is deprecated and it is recommended to use
the new `get_refund_status_by_identifier` method instead.

Author: ghostwriternr

CONTRIBUTING.md

@@ -59,7 +59,7 @@ Ready to contribute? Here's how to set up `setu-python-sdk` for local developmen
 4. Install dependencies and start your virtualenv:
 
     ```
-    $ poetry install -E test -E doc -E dev
+    $ poetry install
     ```
 
 5. Create a branch for local development:

poetry.lock

@@ -29,6 +29,7 @@ PyJWT = "^2.4.0"
 requests = "^2.27.1"
 marshmallow = "^3.14.1"
 marshmallow-oneofschema = "^3.0.1"
+Deprecated = "^1.2.13"
 
 [tool.poetry.dev-dependencies]
 black  = "22.3.0"

pyproject.toml

@@ -1,6 +1,6 @@
 """Top-level package for Setu UPI DeepLinks SDK."""
-from setu.deeplink import Deeplink
 from setu.contract import SetuAPIException
+from setu.deeplink import Deeplink
 
 __version__ = '1.1.1'
 

setu/__init__.py

@@ -2,7 +2,7 @@
 from dataclasses import dataclass
 from datetime import datetime
 from enum import Enum
-from typing import Any, Dict, List, NamedTuple, Optional, Union
+from typing import Any, Dict, List, Literal, NamedTuple, Optional, Union
 
 # Auth types
 AuthType = str  # TODO: Figure out a way to use Literal["JWT", "OAUTH"] across Python versions
@@ -203,8 +203,10 @@ class InitiateBatchRefundResponse:
 
 
 @dataclass
-class BatchRefundStatusResponse:
-    """Batch Refund Status Response."""
+class RefundStatusByIdentifierResponse:
+    """Refund Status By Identifier Response."""
 
-    batch_id: str
     refunds: List[RefundResponseItem]
+
+
+RefundStatusIdentifierType = Literal["batch", "bill"]

setu/contract.py

@@ -4,6 +4,7 @@
 from typing import Any, Callable, Dict, List
 
 import requests
+from deprecated import deprecated
 from requests import Response
 
 from setu.auth import generate_jwt_token, generate_oauth_token
@@ -18,26 +19,27 @@
     AUTH_TYPE_JWT,
     MODE_PRODUCTION,
     AuthType,
-    BatchRefundStatusResponse,
     CreatePaymentLinkResponseData,
     InitiateBatchRefundResponse,
     MockCreditResponseData,
     Mode,
     PaymentLinkStatusResponseData,
     RefundRequestItem,
     RefundResponseItem,
+    RefundStatusByIdentifierResponse,
+    RefundStatusIdentifierType,
     SettlementSplits,
     SetuAPIException,
     ValidationRules,
 )
 from setu.endpoint import get_url_path
 from setu.serial import (
-    BatchRefundStatusResponseSchema,
     CreatePaymentLinkResponseDataSchema,
     InitiateBatchRefundResponseDataSchema,
     MockCreditResponseDataSchema,
     PaymentLinkStatusResponseDataSchema,
     RefundResponseItemSchema,
+    RefundStatusByIdentifierResponseSchema,
     SetuErrorResponseSchema,
 )
 
@@ -213,14 +215,29 @@ def initiate_batch_refund(
         initiate_batch_refund_response_data_schema = InitiateBatchRefundResponseDataSchema()
         return initiate_batch_refund_response_data_schema.load(api_response.json()['data'])
 
+    @deprecated(version="1.2.0", reason="Use the more generic get_refund_status_by_identifier method instead")
     @Decorators.auth_handler
-    def get_batch_refund_status(self, batch_refund_id: str) -> BatchRefundStatusResponse:
+    def get_batch_refund_status(self, batch_refund_id: str) -> RefundStatusByIdentifierResponse:
         """Get batch refund status."""
         api_response = self.session.get(
             "{}/batch/{}".format(get_url_path(API.REFUNDS_BASE, self.auth_type, self.mode), batch_refund_id),
             headers=self.headers,
         )
-        batch_refund_status_response_schema = BatchRefundStatusResponseSchema()
+        batch_refund_status_response_schema = RefundStatusByIdentifierResponseSchema()
+        return batch_refund_status_response_schema.load(api_response.json()['data'])
+
+    @Decorators.auth_handler
+    def get_refund_status_by_identifier(
+        self, identifier_type: RefundStatusIdentifierType, identifier_value: str
+    ) -> RefundStatusByIdentifierResponse:
+        """Get batch refund status."""
+        api_response = self.session.get(
+            "{}/{}/{}".format(
+                get_url_path(API.REFUNDS_BASE, self.auth_type, self.mode), identifier_type, identifier_value
+            ),
+            headers=self.headers,
+        )
+        batch_refund_status_response_schema = RefundStatusByIdentifierResponseSchema()
         return batch_refund_status_response_schema.load(api_response.json()['data'])
 
     @Decorators.auth_handler

setu/deeplink.py

@@ -7,14 +7,14 @@
 from setu.contract import (
     Account,
     Amount,
-    BatchRefundStatusResponse,
     CreatePaymentLinkResponseData,
     InitiateBatchRefundResponse,
     MockCreditResponseData,
     PaymentLink,
     PaymentLinkStatusResponseData,
     Receipt,
     RefundResponseItem,
+    RefundStatusByIdentifierResponse,
     SetuErrorResponseData,
 )
 
@@ -206,13 +206,12 @@ def make_initiate_batch_refund_response_data(self, data, **kwargs):
         return InitiateBatchRefundResponse(**data)
 
 
-class BatchRefundStatusResponseSchema(Schema):
-    """Get Batch Refund Status Response Data Schema."""
+class RefundStatusByIdentifierResponseSchema(Schema):
+    """Get Refund Status By Identifier Response Data Schema."""
 
-    batch_id = fields.Str(data_key="batchID")
     refunds = fields.List(fields.Nested(RefundResponseItemSchema()))
 
     @post_load
     def make_batch_refund_response(self, data, **kwargs):
-        """Deserialize to BatchRefundStatusResponse object."""
-        return BatchRefundStatusResponse(**data)
+        """Deserialize to RefundStatusByIdentifierResponse object."""
+        return RefundStatusByIdentifierResponse(**data)

setu/serial.py

@@ -19,11 +19,11 @@ def test_deeplink(v2_creds):
         mode="SANDBOX",
     )
 
-    bill_amount = 100
+    bill_amount = 1000
     split_account = SplitAccount(
         account_number="123456789",
         account_ifsc="KKBK0000001",
-        amount_value=50,
+        amount_value=500,
     )
 
     try:
@@ -99,6 +99,16 @@ def test_deeplink(v2_creds):
         LOGGER.info(refund_batch_status_response)
         assert refund_batch_status_response.refunds[0].bill_id == link.platform_bill_id
 
+        refund_batch_status_response = dl.get_refund_status_by_identifier(
+            "batch", batch_initiate_refund_response.batch_id
+        )
+        LOGGER.info(refund_batch_status_response)
+        assert refund_batch_status_response.refunds[0].bill_id == link.platform_bill_id
+
+        refund_batch_status_response = dl.get_refund_status_by_identifier("bill", link.platform_bill_id)
+        LOGGER.info(refund_batch_status_response)
+        assert refund_batch_status_response.refunds[0].status == "MarkedForRefund"
+
         # Get individual refund status
         refund_status_response = dl.get_refund_status(batch_initiate_refund_response.refunds[0].id)
         LOGGER.info(refund_status_response)