feat: add payment method and refund functions (#235)

- Add "add_payment_method", "refund_by_amount" and "refund_by_payment_log" functions to beta Referral class
- Add unit tests for new methods
- Add authentication helper function to use referral customer's API key for API calls in unit tests
- Change "Referral User" to "Referral Customer" app-wide, including environmental variables
- Rename old "referral_user" cassettes to "referral_customer"
- Add missing entries to map "bank_"/"card_" prefixes and "BankAccount"/"CreditCard" object types to PaymentMethod class when deserializing JSON
- Add (disabled) unit tests for PaymentMethod deserialization

Author: nwithan8

CHANGELOG.md

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## [Unreleased]
+
+- Added new beta billing functionality for referral customer users, accessible via `EasyPost::Beta::Referral`.
+  - `add_payment_method` to add an existing Stripe bank account or credit card to your EasyPost account.
+  - `refund_by_amount` refunds you wallet balance by a specified amount.
+  - `refund_by_payment_log` refunds you wallet balance by a specified payment log.
+- Fix bug where bank account and credit card payment methods were not deserializing to the `EasyPost::PaymentMethod` class.
+
 ## v4.9.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

@@ -159,5 +159,5 @@ The following are required on every test run:
 Some tests may require an EasyPost user with a particular set of enabled features such as a `Partner` user when creating referrals. We have attempted to call out these functions in their respective docstrings. The following are required when you need to re-record cassettes for applicable tests:
 
 - `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)
+- `PARTNER_USER_PROD_API_KEY` (eg: creating a referral customer)
+- `REFERRAL_CUSTOMER_PROD_API_KEY` (eg: adding a credit card to a referral customer)

docs/EasyPost/Beta/Referral.html

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# PaymentRefund objects represent a refund of a payment.
+class EasyPost::Beta::PaymentRefund < EasyPost::Resource
+end

docs/EasyPost/Referral.html

@@ -55,15 +55,15 @@ def create_easypost_credit_card(referral_api_key, stripe_object_id, priority = '
     end
   end
 
-  # Create a referral user. This function requires the Partner User's API key.
+  # Create a referral customer. This function requires the Partner User's API key.
   # <b>DEPRECATED:</b> Please use <tt>Referral</tt> in the main namespace instead.
   def self.create(params = {}, api_key = nil)
     warn '[DEPRECATION] Please use `Referral.create` in the main namespace instead.'
     response = EasyPost.make_request(:post, '/beta/referral_customers', api_key, { user: params })
     EasyPost::Util.convert_to_easypost_object(response, api_key)
   end
 
-  # Update a referral user. This function requires the Partner User's API key.
+  # Update a referral customer. This function requires the Partner User's API key.
   # <b>DEPRECATED:</b> Please use <tt>Referral</tt> in the main namespace instead.
   def self.update_email(email, user_id, api_key = nil)
     warn '[DEPRECATION] Please use `Referral.update_email` in the main namespace instead.'
@@ -78,15 +78,15 @@ def self.update_email(email, user_id, api_key = nil)
     true
   end
 
-  # Retrieve a list of referral users. This function requires the Partner User's API key.
+  # Retrieve a list of referral customers. This function requires the Partner User's API key.
   # <b>DEPRECATED:</b> Please use <tt>Referral</tt> in the main namespace instead.
   def self.all(params = {}, api_key = nil)
     warn '[DEPRECATION] Please use `Referral.all` in the main namespace instead.'
     response = EasyPost.make_request(:get, '/beta/referral_customers', api_key, params)
     EasyPost::Util.convert_to_easypost_object(response, api_key)
   end
 
-  # Add credit card to a referral user. This function requires the Referral User's API key.
+  # Add credit card to a referral customer. This function requires the Referral Customer's API key.
   # <b>DEPRECATED:</b> Please use <tt>Referral</tt> in the main namespace instead.
   def self.add_credit_card(referral_api_key, number, expiration_month, expiration_year, cvc, priority = 'primary')
     warn '[DEPRECATION] Please use `Referral.add_credit_card` in the main namespace instead.'
@@ -107,4 +107,52 @@ def self.add_credit_card(referral_api_key, number, expiration_month, expiration_
     response = create_easypost_credit_card(referral_api_key, stripe_credit_card_token, priority)
     EasyPost::Util.convert_to_easypost_object(response, referral_api_key)
   end
+
+  # Add a Stripe payment method to a Referral Customer. This function requires the Referral Customer's API key.
+  # @param [String] stripe_customer_id Unique customer ID provided by Stripe.
+  # @param [String] payment_method_reference ID of the card or bank account provided by Stripe.
+  # @param [String] payment_method_type Which priority to save this payment method as on EasyPost, either 'primary' or 'secondary'.
+  # @param [String] api_key Override the API key used for this request.
+  # @return [EasyPost::PaymentMethod] The newly-added payment method.
+  # noinspection RubyParameterNamingConvention
+  def self.add_payment_method(stripe_customer_id, payment_method_reference, priority = 'primary', api_key = nil)
+    wrapped_params = {
+      payment_method: {
+        stripe_customer_id: stripe_customer_id,
+        payment_method_reference: payment_method_reference,
+        priority: priority.downcase,
+      },
+    }
+    response = EasyPost.make_request(:post, '/beta/referral_customers/payment_method', api_key, wrapped_params)
+    # noinspection RubyMismatchedReturnType
+    EasyPost::Util.convert_to_easypost_object(response, api_key)
+  end
+
+  # Refund a Referral Customer's wallet by a specified amount. Refund will be issued to the user's original payment method.
+  # This function requires the Referral Customer's API key.
+  # @param [Integer] amount The amount to refund, in cents.
+  # @param [String] api_key Override the API key used for this request.
+  # @return [EasyPost::Beta::PaymentRefund] The newly-created refund.
+  def self.refund_by_amount(amount, api_key = nil)
+    params = {
+      refund_amount: amount,
+    }
+    response = EasyPost.make_request(:post, '/beta/referral_customers/refunds', api_key, params)
+    # noinspection RubyMismatchedReturnType
+    EasyPost::Util.convert_to_easypost_object(response, api_key) # TODO: Needs "object" or ID prefix to determine object class.
+  end
+
+  # Refund a Referral Customer's wallet for a specified payment log entry. Refund will be issued to the user's original payment method.
+  # This function requires the Referral Customer's API key.
+  # @param [String] payment_log_id Payment log ID to refund.
+  # @param [String] api_key Override the API key used for this request.
+  # @return [EasyPost::Beta::PaymentRefund] The newly-created refund.
+  def self.refund_by_payment_log(payment_log_id, api_key = nil)
+    params = {
+      payment_log_id: payment_log_id,
+    }
+    response = EasyPost.make_request(:post, '/beta/referral_customers/refunds', api_key, params)
+    # noinspection RubyMismatchedReturnType
+    EasyPost::Util.convert_to_easypost_object(response, api_key) # TODO: Needs "object" or ID prefix to determine object class.
+  end
 end

docs/js/search_index.js

@@ -2,7 +2,8 @@
 
 # PaymentMethod objects represent a payment method of a user.
 class EasyPost::PaymentMethod < EasyPost::Resource
-  # <b>DEPRECATED:</b> Please use <tt>Billing class</tt> instead.
+  # List all payment methods associated with the current user.
+  # <b>DEPRECATED:</b> Please use <tt>Billing.retrieve_payment_methods</tt> instead.
   # Deprecated: v4.5.0 - v6.0.0
   def self.all(_filters = {}, api_key = nil)
     warn '[DEPRECATION] `all` is deprecated.  Please use `Billing.retrieve_payment_methods` instead.'

lib/easypost/beta/payment_refund.rb

@@ -55,13 +55,13 @@ def create_easypost_credit_card(referral_api_key, stripe_object_id, priority = '
     end
   end
 
-  # Create a referral user. This function requires the Partner User's API key.
+  # Create a referral customer. This function requires the Partner User's API key.
   def self.create(params = {}, api_key = nil)
     response = EasyPost.make_request(:post, '/v2/referral_customers', api_key, { user: params })
     EasyPost::Util.convert_to_easypost_object(response, api_key)
   end
 
-  # Update a referral user. This function requires the Partner User's API key.
+  # Update a referral customer. This function requires the Partner User's API key.
   def self.update_email(email, user_id, api_key = nil)
     wrapped_params = {
       user: {
@@ -74,13 +74,13 @@ def self.update_email(email, user_id, api_key = nil)
     true
   end
 
-  # Retrieve a list of referral users. This function requires the Partner User's API key.
+  # Retrieve a list of referral customers. This function requires the Partner User's API key.
   def self.all(params = {}, api_key = nil)
     response = EasyPost.make_request(:get, '/v2/referral_customers', api_key, params)
     EasyPost::Util.convert_to_easypost_object(response, api_key)
   end
 
-  # Add credit card to a referral user. This function requires the Referral User's API key.
+  # Add credit card to a referral customer. This function requires the Referral Customer's API key.
   def self.add_credit_card(referral_api_key, number, expiration_month, expiration_year, cvc, priority = 'primary')
     easypost_stripe_api_key = retrieve_easypost_stripe_api_key
 

lib/easypost/beta/referral.rb

@@ -7,9 +7,11 @@ module EasyPost::Util
   BY_PREFIX = {
     'ak' => EasyPost::ApiKey,
     'adr' => EasyPost::Address,
+    'bank' => EasyPost::PaymentMethod,
     'batch' => EasyPost::Batch,
     'brd' => EasyPost::Brand,
     'ca' => EasyPost::CarrierAccount,
+    'card' => EasyPost::PaymentMethod,
     'cstinfo' => EasyPost::CustomsInfo,
     'cstitem' => EasyPost::CustomsItem,
     'es' => EasyPost::EndShipper,
@@ -37,10 +39,12 @@ module EasyPost::Util
   BY_TYPE = {
     'Address' => EasyPost::Address,
     'ApiKey' => EasyPost::ApiKey,
+    'BankAccount' => EasyPost::PaymentMethod,
     'Batch' => EasyPost::Batch,
     'Brand' => EasyPost::Brand,
     'CarbonOffset' => EasyPost::CarbonOffset,
     'CarrierAccount' => EasyPost::CarrierAccount,
+    'CreditCard' => EasyPost::PaymentMethod,
     'CustomsInfo' => EasyPost::CustomsInfo,
     'CustomsItem' => EasyPost::CustomsItem,
     'EndShipper' => EasyPost::EndShipper,
@@ -147,6 +151,7 @@ def self.convert_to_easypost_object(response, api_key, parent = nil, name = nil)
       response.map { |i| convert_to_easypost_object(i, api_key, parent) }
     when Hash
       if (cls_name = response[:object])
+        # TODO: This line was never hit when debugging all unit tests, suggesting it's broken
         cls = BY_TYPE[cls_name]
       elsif response[:id]
         if response[:id].index('_').nil?

lib/easypost/payment_method.rb

@@ -2,34 +2,34 @@
 
 require 'spec_helper'
 
-REFERRAL_USER_PROD_API_KEY = ENV['REFERRAL_USER_PROD_API_KEY'] || '123'
+REFERRAL_CUSTOMER_PROD_API_KEY = ENV['REFERRAL_CUSTOMER_PROD_API_KEY'] || '123'
 
 describe EasyPost::Beta::Referral, :authenticate_partner do
   describe '.create' do
-    it 'creates a referral user' do
+    it 'creates a referral customer' do
       # This test requires a partner user's production API key via PARTNER_USER_PROD_API_KEY.
-      created_referral_user = described_class.create(
+      created_referral_customer = described_class.create(
         name: 'test user',
         email: '[email protected]',
         phone: '8888888888',
       )
 
-      expect(created_referral_user).to be_an_instance_of(EasyPost::User)
-      expect(created_referral_user.id).to match('user_')
-      expect(created_referral_user.name).to eq('test user')
+      expect(created_referral_customer).to be_an_instance_of(EasyPost::User)
+      expect(created_referral_customer.id).to match('user_')
+      expect(created_referral_customer.name).to eq('test user')
     end
   end
 
   describe '.update_email' do
-    it 'updates a referral user' do
+    it 'updates a referral customer' do
       # This test requires a partner user's production API key via PARTNER_USER_PROD_API_KEY.
-      referral_users = described_class.all(
+      referral_customers = described_class.all(
         page_size: Fixture.page_size,
       )
 
       updated_user = described_class.update_email(
         '[email protected]',
-        referral_users.referral_customers[0].id,
+        referral_customers.referral_customers[0].id,
       )
 
       expect(updated_user).to eq(true)
@@ -38,25 +38,25 @@
 
   describe '.all' do
     # This test requires a partner user's production API key via PARTNER_USER_PROD_API_KEY.
-    it 'retrieve all referral users' do
-      referral_users = described_class.all(
+    it 'retrieve all referral customers' do
+      referral_customers = described_class.all(
         page_size: Fixture.page_size,
       )
 
-      referral_users_array = referral_users.referral_customers
+      referral_customers_array = referral_customers.referral_customers
 
-      expect(referral_users_array.count).to be <= Fixture.page_size
-      expect(referral_users.has_more).not_to be_nil
-      expect(referral_users_array).to all(be_an_instance_of(EasyPost::User))
+      expect(referral_customers_array.count).to be <= Fixture.page_size
+      expect(referral_customers.has_more).not_to be_nil
+      expect(referral_customers_array).to all(be_an_instance_of(EasyPost::User))
     end
   end
 
   describe '.add_credit_card' do
-    it 'adds a credit card to a referral user account' do
+    it 'adds a credit card to a referral customer account' do
       # This test requires a partner user's production API key via PARTNER_USER_PROD_API_KEY
-      # as well as one of that user's referral's production API keys via REFERRAL_USER_PROD_API_KEY.
+      # as well as one of that user's referral's production API keys via REFERRAL_CUSTOMER_PROD_API_KEY.
       credit_card = described_class.add_credit_card(
-        REFERRAL_USER_PROD_API_KEY,
+        REFERRAL_CUSTOMER_PROD_API_KEY,
         Fixture.credit_card_details['number'],
         Fixture.credit_card_details['expiration_month'],
         Fixture.credit_card_details['expiration_year'],
@@ -73,7 +73,7 @@
 
       expect {
         described_class.add_credit_card(
-          REFERRAL_USER_PROD_API_KEY,
+          REFERRAL_CUSTOMER_PROD_API_KEY,
           Fixture.credit_card_details['number'],
           Fixture.credit_card_details['expiration_month'],
           Fixture.credit_card_details['expiration_year'],
@@ -82,4 +82,42 @@
       }.to raise_error(StandardError).with_message('Could not send card details to Stripe, please try again later.')
     end
   end
+
+  describe '.add_payment_method', :authenticate_referral do
+    it 'adds a Stripe card or bank account to a referral customer account' do
+      # This test requires a referral customer's production API key via REFERRAL_CUSTOMER_PROD_API_KEY.
+      expect {
+        described_class.add_payment_method(
+          'cus_123',
+          'ba_123',
+        )
+      }.to raise_error(EasyPost::Error).with_message('Invalid Payment Gateway Reference.')
+    end
+  end
+
+  describe '.refund_by_amount', :authenticate_referral do
+    it 'refunds a referral user by a specific amount' do
+      # This test requires a referral customer's production API key via REFERRAL_CUSTOMER_PROD_API_KEY.
+      expect {
+        described_class.refund_by_amount(
+          2000,
+        )
+      }.to raise_error(EasyPost::Error).with_message(
+        'Refund amount is invalid. Please use a valid amount or escalate to finance.',
+      )
+    end
+  end
+
+  describe '.refund_by_payment_log', :authenticate_referral do
+    it 'refunds a referral user by a specific payment log entry' do
+      # This test requires a referral customer's production API key via REFERRAL_CUSTOMER_PROD_API_KEY.
+      expect {
+        described_class.refund_by_payment_log(
+          'paylog_123',
+        )
+      }.to raise_error(EasyPost::Error).with_message(
+        'We could not find a transaction with that id.',
+      )
+    end
+  end
 end