πŸ’ΈConnected Accounts

What are connected accounts?

Connected accounts are users within your platform that you wish to assist with collecting payments and making money via your platform. Some real world examples of this are:

  • Merchants / stores on a deliveroo

  • Drivers on Uber

  • Hosts on AirBNB

  • Sellers on Etsy

  • Stores on Shopify

With most of the items in the list, the customers transact directly with the platform, and the merchant / host / driver is paid out by the platform at a later time or date. This type of model is facilitied within Stripe Connect using Desintation charges or Transfers. The last item in the list is generally an exception to the others. With Shopify, the customers are direct customers of your website, which happens to be hosted by shopify. And whilst they process your payments, you are respnosible for those payments including refunds and chargebacks. This more direct model is facilitated within Stripe using Direct Charges.

Setting up the model

Add the Billable trait to your model. If you are already using the traditionanl Cashier Billable trait, you can add them both by giving it an alias. You can use them individually or together. If you are using the ConnectBillable trait, the model should also implement the StripeAccount interface.

For the purposes of the examples outlined below we will replicate the first and last marketplace style payment models where you have a Store model and a Customer model.

Any model you add the ConnectBillable trait to, MUST have an "email" field as this is the minimum requirement for stripe. The field must always be called email.

namespace App\Models;

use Lanos\CashierConnect\Contracts\StripeAccount;
use Laravel\Cashier\Billable as CashierBillable;
use Lanos\CashierConnect\Billable as ConnectBillable;

class Store extends Model implements StripeAccount
{
    use CashierBillable;
    use ConnectBillable;

}

Once you add that trait, your Store model will immediately have access to a ton of new functions which allow it to exist within Stripe.

To create this store within Stripe as a Connected Account, simply run the following command.

$store = Store::find($idofStore);

// Param 1 - Account Type
// Param 2 - Account Data
$connectedAccount = $store->createAsStripeAccount('standard', $data);

This function will create the connected account in stripe, and bind it to the model.

Retrieve stripe account from the model

To retrieve the account from stripe in future you can simply do the following:

$store->asStripeAccount();

Checking if a model exists in stripe or not

Running the below function will return a boolean. Also a lot of functions such as payments and transfers will first check if both parties exist, if not, it will throw an exception.

$store->hasStripeAccount();

Deleting the stripe connected Account

If you do not want your model to exist in stripe connect any longer you can delete them by doing the following.

$store->deleteStripeAccount();

Configuring Platform Fees

Against your model you can set the application fee settings. This can either be a percentage or a fixed number. Below both examples are shown of the properties being set against the store model.

When using fixed transaction fee's it's important to note the fees must not be higher than the amount of the transaction. A percentage based fee is always encouraged.

Percentage based platform fee

use Lanos\CashierConnect\Billable;

class Store extends Model implements StripeAccount{

    use Billable;
    
    public $commission_type = 'percentage';
    public $commission_rate = 5;

}

Fixed based platform fee

use Lanos\CashierConnect\Billable;

class Store extends Model implements StripeAccount{

    use Billable;
    
    public $commission_type = 'fixed';
    public $commission_rate = 500; // E.G. Β£5 application fee

}

Special Circumstances

Every platform is different, and as developers we all have our own ways of doing things. Some of those alternative circumstances are considered and catered to below.

Custom Primary Key Usage

This package will correctly recognise your custom primary key, as long as you use the following correctly.

protected $primaryKey = 'your_id';

UUID Usage

Some people prefer to use Ordered UUID's, this has become more common since Laravel 9. The package will automatically detect if you are using a non integer primary key on your model, as long as you have the following property set on your model it should work fine.

public $incrementing = false;

Models are cross compatible, meaning if your store model had a UUID but you customer model had an incrementing integer, it would still work.

Last updated