Merge pull request #249 from EasyPost/payment_method_refund

feat: add payment method and refund functions

Author: Justintime50

CHANGELOG.md

@@ -1,5 +1,12 @@
 # CHANGELOG
 
+## Next Release
+
+- Adds new beta billing functionality for ReferralCustomer users
+  - `add_payment_method` can add a pre-existing Stripe bank account or credit card to your EasyPost account
+  - `refund_by_amount` refunds your wallet by a dollar amount
+  - `refund_by_payment_log` refunds you wallet by a PaymentLog ID
+
 ## v7.7.0 (2022-12-07)
 
 - Routes requests for creating a carrier account with a custom workflow (eg: FedEx, UPS) to the correct endpoint when using the `create` function

README.md

@@ -118,4 +118,4 @@ Some tests may require an EasyPost user with a particular set of enabled feature
 
 - `USPS_CARRIER_ACCOUNT_ID` (eg: one-call buying a shipment for non-EasyPost employees)
 - `PARTNER_USER_PROD_API_KEY` (eg: creating a referral user)
-- `REFERRAL_USER_PROD_API_KEY` (eg: adding a credit card to a referral user)
+- `REFERRAL_CUSTOMER_PROD_API_KEY` (eg: adding a credit card to a referral user)

easypost/beta/referral.py

@@ -109,6 +109,67 @@ def add_credit_card(
         )
         return convert_to_easypost_object(response)
 
+    @staticmethod
+    def add_payment_method(
+        stripe_customer_id: str,
+        payment_method_reference: str,
+        primary_or_secondary: str = "primary",
+    ) -> Dict[str, Any]:
+        """Add a Stripe payment method to your EasyPost account.
+
+        This endpoint uses a user's personal Stripe account. The `stripe_customer_id`
+        and `payment_method_reference` IDs both come from Stripe. By adding these to
+        EasyPost, we will associate your Stripe payment method with either your primary
+        or secondary EasyPost payment method.
+        """
+        requestor = Requestor()
+        wrapped_params = {
+            "payment_method": {
+                "stripe_customer_id": stripe_customer_id,
+                "payment_method_reference": payment_method_reference,
+                "priority": primary_or_secondary,
+            }
+        }
+
+        response, api_key = requestor.request(
+            method=RequestMethod.POST,
+            url="/referral_customers/payment_method",
+            params=wrapped_params,
+            beta=True,
+        )
+
+        return convert_to_easypost_object(response=response, api_key=api_key)
+
+    @staticmethod
+    def refund_by_amount(refund_amount: int) -> Dict[str, Any]:
+        """Refund a ReferralCustomer wallet by specifying an amount."""
+        requestor = Requestor()
+        wrapped_params = {"refund_amount": refund_amount}
+
+        response, api_key = requestor.request(
+            method=RequestMethod.POST,
+            url="/referral_customers/refunds",
+            params=wrapped_params,
+            beta=True,
+        )
+
+        return convert_to_easypost_object(response=response, api_key=api_key)
+
+    @staticmethod
+    def refund_by_payment_log(payment_log_id: str) -> Dict[str, Any]:
+        """Refund a ReferralCustomer wallet by specifying a payment log ID to completely refund."""
+        requestor = Requestor()
+        wrapped_params = {"payment_log_id": payment_log_id}
+
+        response, api_key = requestor.request(
+            method=RequestMethod.POST,
+            url="/referral_customers/refunds",
+            params=wrapped_params,
+            beta=True,
+        )
+
+        return convert_to_easypost_object(response=response, api_key=api_key)
+
     @staticmethod
     def _retrieve_easypost_stripe_api_key() -> str:
         """Retrieve EasyPost's Stripe public API key."""

easypost/referral.py

@@ -15,6 +15,7 @@
 )
 
 
+# TODO: Rename `Referral` to `ReferralCustomer` and have the module name match as well
 class Referral:
     @staticmethod
     def create(
@@ -94,7 +95,11 @@ def add_credit_card(
 
         try:
             stripe_token = Referral._create_stripe_token(
-                number, expiration_month, expiration_year, cvc, easypost_stripe_api_key
+                number,
+                expiration_month,
+                expiration_year,
+                cvc,
+                easypost_stripe_api_key,
             )
         except Exception:
             raise Error(message="Could not send card details to Stripe, please try again later")

tests/cassettes/test_beta_referral_add_payment_method.yaml

@@ -17,6 +17,7 @@
 EASYPOST_TEST_API_KEY = os.getenv("EASYPOST_TEST_API_KEY")
 EASYPOST_PROD_API_KEY = os.getenv("EASYPOST_PROD_API_KEY")
 PARTNER_USER_PROD_API_KEY = os.getenv("PARTNER_USER_PROD_API_KEY", "123")
+REFERRAL_CUSTOMER_PROD_API_KEY = os.getenv("REFERRAL_CUSTOMER_PROD_API_KEY", "123")
 
 SCRUBBED_STRING = "<REDACTED>"
 SCRUBBED_ARRAY: List = []
@@ -71,6 +72,15 @@ def partner_prod_api_key():
     easypost.api_key = default_key
 
 
+@pytest.fixture
+def referral_customer_prod_api_key():
+    """If a test needs to use the referral customer prod api key, make it depend on this fixture."""
+    default_key = easypost.api_key
+    easypost.api_key = REFERRAL_CUSTOMER_PROD_API_KEY
+    yield
+    easypost.api_key = default_key
+
+
 @pytest.fixture(autouse=True)
 def check_expired_cassettes(expiration_days: int = 180, throw_error: bool = False):
     """Checks for expired cassettes and throws errors if they are too old and must be re-recorded."""