cash_out 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 89d3b16a65640bfe86c9c9b08db3415d802b5daa
-  data.tar.gz: e7264ed0558c1dd2ff12a1741ca08b1f6627c03a
+  metadata.gz: e35c084e12b884895299c46ecc486f3e55fde8af
+  data.tar.gz: 716d1175f5fdf7d85ff0b065c1acae93c4ebc179
 SHA512:
-  metadata.gz: ba3d8f16518bd1b28926a4a1d28cd8a70f867e5c7060f6c684429ef0191eef143e5b02ac558b1a0bb23ccbaea1cda1c7d57b08b49d7f701f83706bbbbb5745de
-  data.tar.gz: fa92ab005a40e0e61ef6540bacc53f11f6789dee1f3b7f0a2637676e6d496389fec00a47ad6ea08dcfcc170c8d3bae3614b80386fa1f16d7e7a40431019ab94d
+  metadata.gz: a511c1848565781927821a57abc2c45f485965f42a7ed97cb73d65772e8d0dd5851d8c84ed3f8c5231742c743b7742751330910a40910be4ed3d6407a8660096
+  data.tar.gz: a7d2aace28c3984608cd74131798dc4fddd2b1a919574d50d2894bc542cd2441e78ecc53f408fc1ef3dcce19974fc8974cfa97806a038123cc39e902d95f4545

data/.gitignore

@@ -1 +1,2 @@
 spec/examples.txt
+assets/title-image.psd

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cash_out (0.0.1)
+    cash_out (0.0.3)
       active_interaction (~> 3.6)
       railties (< 6.0)
       stripe (~> 3.21)

data/README.md

@@ -1,4 +1,4 @@
-# Cash Out
+![Cash Out](assets/title-image.jpg)
 
 A gem developed with the express purpose of reducing development time when integrating
 with Stripe payments.
@@ -6,13 +6,42 @@ with Stripe payments.
 This gem is targeted at API development and assumes your frontend is able to generate
 and send tokenized payment data to your endpoints.
 
+## Contents
+1. [Installation](#installation)
+1. [Configuration](#configuration)
+1. [Usage](#usage)
+    1. [Handling Credit Cards](#creating-a-stripe-customer)
+        1. [Creating a Stripe Customer](#creating-a-stripe-customer)
+        1. [Deleting a Stripe Customer](#deleting-a-stripe-customer)
+    1. [Handling Bank Accounts](#creating-a-stripe-connect-custom-account)
+        1. [Creating a Stripe Connect Custom Account](#creating-a-stripe-connect-custom-account)
+            1. [Further Reading](#further-reading)
+        1. [Deleting a Stripe Connect Custom Account](#deleting-a-stripe-connect-custom-account)
+    1. [Creating a Charge](#creating-a-charge)
+        1. [Without a Payout](#without-a-payout)
+        1. [With a Payout](#with-a-payout)
+    1. [Creating a Transfer](#creating-a-transfer)
+
+
 ## Installation
 
-1. Add `gem cash_out` to your Gemfile
+1. Add `gem cash_out` to your Gemfile.
 1. `bundle install`
 1. `rails generate cash_out:install`
-1. Update the items in `config/initializers/cash_out.rb` with your Stripe api keys
-1. Create a migration to add a `stripe_id` field to `User` or whichever model will hold the Stripe token
+1. Update the items in `config/initializers/cash_out.rb` with your Stripe API keys.
+1. Create a migration to add a `stripe_id` (String) field to `User` or whichever model will hold the Stripe token.
+1. If using Stripe Connect (for making payouts), add `date_of_birth`(Date) to your `User` as well.
+
+## Configuration
+CashOut needs to be configured with your Stripe API keys. You can find the config file
+in `config/initializers/cash_out.rb`. If it's not there, run `rails generate cash_out:install`.
+
+```ruby
+CashOut.configure do |config|
+  config.stripe_publishable_key = 'your_stripe_public_key'
+  config.stripe_secret_key = 'your_stripe_secret_key'
+end
+```
 
 ## Usage
 
@@ -24,7 +53,7 @@ and will return an appropriate service object.
 Stripe Customer objects are used for making credit card purchases. You can create a
 Stripe Customer and store the token on your User with the following code.
 
-Inside your controller, add:
+Sample Code:
 ```ruby
 def create
   CashOut::Payments::Customer::Create.run(customer_params)
@@ -39,12 +68,154 @@ end
 
 To remove payment information from your user, run the appropriate delete service
 
-Inside your controller, add:
+Sample Code:
 ```ruby
 def destroy
   CashOut::Payments::Customer::Delete.run(user: current_user)
 end
 ```
 
-Note: This currently does not delete the payment information from Stripe. Support
-for this will be added in a future release.
+Note: This currently deletes the entire Customer account. Support for deleting
+individual cards will be added in a future release.
+
+### Creating a Stripe Connect Custom Account
+
+A Stripe Connect Custom Account is used when your app needs to pay independent
+contractors. This will connect the user's bank account with a Stripe account
+you create for them. This will allow you to make payments out to the user's account
+and make transfers from the user's bank account to settle any outstanding balance.
+
+Setting up a Connect Account requires several params. `user` can be any object
+that responds to `stripe_id`, `valid?`, `save`, `date_of_birth`, `first_name`, and `last_name`.
+
+| Param        | Description  |
+:--------------|:------------:|
+| **user** | The user receiving the account. It must respond to `stripe_id`, `valid?`, `save`, `date_of_birth`, `first_name`, and `last_name`
+| **external_account_token** | Tokenized bank account info, generated via frontend app.
+| **ip_address** | The user's current ip address. Can be accessed via `request.remote_ip`
+| **legal_entity_type** | Must be `"individual"` or `"company"`
+| **ssn_last_4** | The last 4 digits of the user's SSN
+| **stripe_terms_accepted** | The frontend must link to the [Stripe Connected Account Agreement](https://stripe.com/connect-account/legal), and the user must accept it.
+| **legal_entity_address** | The address of the individual user or the user's business. Must contain `line1`, `city`, `state`, `country`, and `postal_code`. `line2` is optional.
+
+Sample Code:
+```ruby
+def create
+  CashOut::Connect::Account::Create.run(account_params)
+end
+
+def account_params
+  {
+    user: current_user,
+    external_account_token: params[:external_account_token],
+    ip_address: ,
+    legal_entity_type: params[:legal_entity_type],
+    ssn_last_4: params[:ssn_last_4],
+    stripe_terms_accepted: params[:stripe_terms_accepted],
+    legal_entity_address: legal_entity_params
+  }
+end
+
+def legal_entity_params
+  params.require(:address).permit(
+    :line1,
+    :line2,
+    :city,
+    :state,
+    :country,
+    :postal_code
+  )
+end
+```
+
+#### Further Reading
+Further documentation regarding Connect accounts may be found on
+[Stripe's Official Connect Documentation](https://stripe.com/docs/api#account)
+
+### Deleting a Stripe Connect Custom Account
+
+To remove payment information from your user, run the appropriate delete service
+
+Sample Code:
+```ruby
+def destroy
+  CashOut::Connect::Account::Delete.run(user: current_user)
+end
+```
+
+### Creating a Charge
+
+#### Without a Payout
+When creating a charge without a payout, you can send just 2 params
+
+| Param        | Description  |
+:--------------|:------------:|
+| **payor** | The user being charged. It must respond to `stripe_id`. |
+| **amount_to_charge** | The amount of money in cents to be charged. Must be a positive integer. |
+
+**Example:**
+
+```ruby
+CashOut::Charge::Create.run(charge_params)
+
+def charge_params
+  { payor: paying_user, amount_to_charge: charge_in_cents }
+end
+```
+
+#### With a Payout
+Making a charge with a payout is a little more complex, but CashOut aims to handle
+the difficult parts for you. There are 4 params that need to be sent:
+
+| Param        | Description  |
+:--------------|:------------:|
+| **payor** | The user being charged. It must respond to `stripe_id`. |
+| **amount_to_charge** | The amount of money in cents to be charged. Must be a positive integer. |
+| **payee** | The user receiving payment. It also must respond to `stripe_id` |
+| **amount_to_payout** | The amount of money in cents to be paid out. Must be an integer. |
+
+**Example:**
+
+```ruby
+CashOut::Charge::Create.run(charge_params)
+
+def charge_params
+  {
+    payor: paying_user,
+    amount_to_charge: charge_in_cents,
+    payee: user_getting_paid,
+    amount_to_payout: payout_in_cents
+  }
+end
+```
+
+It's important to know that `amount_to_payout` can be either positive or negative.
+
+In the case of a positive payout, the user will receive the `amount_to_payout` in their Stripe account.
+For negative payouts, the `amount_to_payout` will be transfered from the user to the platform (business owned)
+Stripe account.
+
+### Creating a Transfer
+CashOut attempts to handle transfers automatically. However, should the case arise that you need to create
+one manually, you can do so with the following.
+
+
+| Param        | Description  |
+:--------------|:------------:|
+| **payee** | The user receiving payment. It also must respond to `stripe_id` |
+| **amount_to_payout** | The amount of money in cents to be paid out. Must be an integer. |
+
+```ruby
+CashOut::Connect::Transfer::Create.run(transfer_params)
+
+def transfer_params
+  {
+    payee: user_getting_paid,
+    amount_to_payout: payout_in_cents
+  }
+end
+```
+
+**Important Note** When creating a transfer without a corresponding payment, or when the transfer
+amount exceeds the amount of associated charges, the platform Stripe account **MUST** have enough
+available funds to cover the transfer, or the transfer will fail.

data/config/locales/en.yml

@@ -1,5 +1,10 @@
 en:
   cash_out:
+    connect:
+      is_required: "is required"
+      account_already_exists: "User already has a Stripe account"
+    charge:
+      invalid_charge_amount: "The charge amount must be a positive integer"
     customer:
       account_already_exists: "User already has a Stripe account"
       invalid_card: "The card entered is not valid"

data/lib/cash_out.rb

@@ -1,10 +1,20 @@
 # frozen_string_literal: true
+# Config
 require 'cash_out/configuration'
 
+# External dependencies
 require 'active_interaction'
 require 'stripe'
+
+# Core Files
 require 'cash_out/base'
 require 'cash_out/service_base'
+
+# Other Services
+require 'cash_out/charge/create'
+require 'cash_out/connect/account/create'
+require 'cash_out/connect/account/delete'
+require 'cash_out/connect/transfer/create'
 require 'cash_out/payments/customer/create'
 require 'cash_out/payments/customer/delete'
 

data/lib/cash_out/charge/create.rb

@@ -0,0 +1,87 @@
+module CashOut
+  module Charge
+    class Create < ::CashOut::ServiceBase
+      interface :payor, methods: %i(stripe_id)
+      interface :payee, methods: %i(stripe_id), default: nil
+      integer :amount_to_charge
+      integer :amount_to_payout, default: 0
+
+      validate :charges_are_positive
+
+      def execute
+        create_charge
+      end
+
+      private
+
+      def create_charge
+        # Stripe won't let you create a destination charge if the payout exceeds the charges
+        payout_less_than_charge? ? destination_charge : standalone_charge
+      end
+
+      def payout_less_than_charge?
+        amount_to_payout.positive? && amount_to_payout < amount_to_charge
+      end
+
+      def destination_charge
+        # This is what we should do in most cases
+        # amount_to_charge is charged to payor
+        # amount_to_payout goes to payee
+        # Remainder is kept in company Stripe account
+        # https://stripe.com/docs/connect/destination-charges#collecting-platform-fees
+        return errors.add(:stripe, I18n.t('cash_out.charge.no_payee')) unless payee
+        charge_payor(destination_charge_params)
+      end
+
+      def standalone_charge
+        # When dealing with a negative payout, we must create the charge and transfer separately
+        charge_payor(standalone_charge_params)
+        initiate_transfer
+      end
+
+      def initiate_transfer
+        CashOut::Connect::Transfer::Create.run(payee: payee, amount_to_payout: amount_to_payout)
+      end
+
+      def charge_payor(*args)
+        Stripe::Charge.create(*args)
+      rescue *STRIPE_ERRORS => e
+        errors.add(:stripe, e.to_s)
+        e.json_body
+      end
+
+      def standalone_charge_params
+        # Charges the payor the total amount owed
+        {
+          amount: amount_to_charge,
+          currency: "usd",
+          description: "",
+          customer: payor.stripe_id
+        }
+      end
+
+      def destination_charge_params
+        # Charges the payor the total amount owed
+        # Sends payout amount to payee
+        {
+          amount: amount_to_charge,
+          currency: "usd",
+          description: "",
+          customer: payor.stripe_id,
+          destination: {
+            account: payee.stripe_id,
+            amount: amount_to_payout
+          }
+        }
+      end
+
+      def charges_are_positive
+       # Charge will fail if balance due is $0.00
+       # Charge should never be negative
+       unless amount_to_charge.positive?
+         errors.add(:stripe,I18n.t('cash_out.charge.invalid_charge_amount'))
+       end
+      end
+    end
+  end
+end

data/lib/cash_out/connect/account/create.rb

@@ -0,0 +1,93 @@
+module CashOut
+  module Connect
+    module Account
+      class Create < ::CashOut::ServiceBase
+        interface :user, methods: %i(stripe_id valid? save date_of_birth first_name last_name)
+        string :external_account_token
+        string :ip_address
+        string :legal_entity_type
+        string :ssn_last_4
+        boolean :stripe_terms_accepted, default: false
+        hash :legal_entity_address do
+          string :line1
+          string :line2, default: ""
+          string :city
+          string :state
+          string :country
+          string :postal_code
+        end
+
+        validates :stripe_terms_accepted, presence: true
+        validate :no_existing_stripe_account, :legal_entity_must_be_present
+
+        def execute
+          account = create_stripe_account
+          user.stripe_id = account["id"] if account.is_a?(Stripe::Account)
+          validate_and_save(user)
+        end
+
+        private
+
+        def create_stripe_account
+          Stripe::Account.create(stripe_account_params)
+        rescue *STRIPE_ERRORS => e
+          errors.add(:stripe, e.to_s)
+        end
+
+        def stripe_account_params
+          {
+            type: "custom",
+            country: "US",
+            tos_acceptance: {
+              date: Time.current.to_i,
+              ip: ip_address,
+            },
+            payout_schedule: {
+              delay_days: 2,
+              interval: "daily"
+            },
+            debit_negative_balances: true,
+            legal_entity: legal_entity_params,
+            external_account: external_account_token
+          }
+        end
+
+        def legal_entity_params
+          {
+            type: legal_entity_type,
+            first_name: user.first_name,
+            last_name: user.last_name,
+            ssn_last_4: ssn_last_4,
+            dob: {
+              day: user.date_of_birth.day,
+              month: user.date_of_birth.month,
+              year: user.date_of_birth.year,
+            },
+            address: {
+              line1: legal_entity_address[:line1],
+              line2: legal_entity_address[:line2],
+              city: legal_entity_address[:city],
+              state: legal_entity_address[:state],
+              country: legal_entity_address[:country],
+              postal_code: legal_entity_address[:postal_code]
+            }
+          }
+        end
+
+        def no_existing_stripe_account
+          errors.add(:stripe, I18n.t('cash_out.connect.account_already_exists')) if user.stripe_id.present?
+        end
+
+        def legal_entity_must_be_present
+          missing_fields.each { |mf| errors.add(mf, I18n.t('cash_out.connect.is_required')) }
+        end
+
+        def missing_fields
+          legal_entity_address.except(:line2).map do |key, value|
+            key.to_sym if value.empty?
+          end.compact
+        end
+      end
+    end
+  end
+end

data/lib/cash_out/connect/account/delete.rb

@@ -0,0 +1,23 @@
+module CashOut
+  module Connect
+    module Account
+      class Delete < ::CashOut::ServiceBase
+        interface :user, methods: %i(stripe_id save valid?)
+
+        def execute
+          delete_account
+          user.stripe_id = nil
+          validate_and_save(user)
+        end
+
+        private
+
+        def delete_account
+          Stripe::Account.retrieve(user.stripe_id).delete
+        rescue *STRIPE_ERRORS => e
+          errors.add(:stripe, e.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/cash_out/connect/transfer/create.rb

@@ -0,0 +1,69 @@
+module CashOut
+  module Connect
+    module Transfer
+      class Create < ::CashOut::ServiceBase
+        interface :payee, methods: %i(stripe_id)
+        integer :amount_to_payout
+
+        def execute
+          initiate_transfer
+        end
+
+        private
+
+        def initiate_transfer
+          Stripe::Transfer.create(*params)
+        rescue *STRIPE_ERRORS => e
+          errors.add(:stripe, e.to_s)
+          e.json_body
+        end
+
+        def params
+          # Stripe does not allow negative transfers, so we must change the params accordingly
+          amount_to_payout.positive? ? positive_payout_params : negative_payout_params
+        end
+
+        def negative_payout_params
+          # Makes a transfer from the payee to the platform account for amount owed
+          # https://stripe.com/docs/connect/account-debits#transferring-from-a-connected-account
+          [
+            {
+              amount: amount_to_payout.abs,
+              currency: "usd",
+              description: "",
+              destination: platform_stripe_account.id
+            },
+            {
+              stripe_account: payee.stripe_id
+            }
+          ]
+        end
+
+        def positive_payout_params
+          # Only runs when payout is positive but payout amount > charges
+          # Makes a transfer from platform account to payee
+          # Platform Stripe Account balance MUST be greater than transfer amount
+          [
+            {
+              amount: amount_to_payout,
+              currency: "usd",
+              description: "",
+              destination: payee.stripe_id
+            },
+            {
+              stripe_account: platform_stripe_account.id,
+            }
+          ]
+        end
+
+        def platform_stripe_account
+          # Calling retrieve without a param retrieves the platform account
+          # In test mode, create charges with 4000 0000 0000 0077 to add funds
+          # https://stripe.com/docs/testing#cards-responses
+          @platform_stripe_account ||= Stripe::Account.retrieve
+        end
+      end
+    end
+  end
+end
+

data/lib/cash_out/payments/customer/create.rb

@@ -2,7 +2,7 @@ module CashOut
   module Payments
     module Customer
       class Create < ::CashOut::ServiceBase
-        interface :user, methods: [:stripe_id]
+        interface :user, methods: %i(stripe_id valid? save)
         string :stripe_token, default: nil
 
         validate :customer_is_nil

data/lib/cash_out/version.rb

@@ -1,4 +1,4 @@
 module CashOut
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end
 

data/lib/generators/cash_out/templates/cash_out_config.rb

@@ -1,5 +1,4 @@
 CashOut.configure do |config|
   config.stripe_publishable_key = ''
   config.stripe_secret_key = ''
-  config.stripe_api_key = ''
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cash_out
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Tyler Rockwell
@@ -149,13 +149,18 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- assets/title-image.jpg
 - bin/console
 - bin/setup
 - cash_out.gemspec
 - config/locales/en.yml
 - lib/cash_out.rb
 - lib/cash_out/base.rb
+- lib/cash_out/charge/create.rb
 - lib/cash_out/configuration.rb
+- lib/cash_out/connect/account/create.rb
+- lib/cash_out/connect/account/delete.rb
+- lib/cash_out/connect/transfer/create.rb
 - lib/cash_out/payments/customer/create.rb
 - lib/cash_out/payments/customer/delete.rb
 - lib/cash_out/service_base.rb