Connect Setup

Stripe Connect lets you send payments to connected sub-accounts, and collect platform fee's with just a little bit of extra config.

Upgrade to Pro Connect is a Pro only feature. You'll need to upgrade to use it.

Connect requires some extra setup You'll need to configure things on both your Stripe account, and in the Charge settings to get things ready to go

Setup #

Setting up Connect on your site has a few required steps.

  1. Configure your Connect from both the Stripe and Charge settings
  2. Add the Charge Connect fieldtype to your merchant's Craft elements
  3. Update your templates
  4. Connect and Test

1. Configure Stripe and Charge #

You can enable connect on your Charge install from Charge > Settings > Connect.

When enabled, you'll see the 3 core parts of the setup. Fieldtype setup (which we'll cover in step 2), Platform Ids and Redirect Urls.

Platform Ids

You'll need to go to your Stripe account dashboard > settings to get your platform Ids. For your master platform you'll have 2 - a development and production id. Grab those and enter them here.

These are used under the hood to allow accounts to connect to your master stripe account. Development is used when in test mode, Production in live mode.

Redirect Urls

The redirect urls are used during the connection flow for new sub-accounts, as part of the OAuth callback step.

When a user connects a stripe account, they'll be moved off site to the Stripe platform to log in, or create a Stripe account, and then authorise it for use with your platform account.

These redirect urls are used as a whitelist of where Stripe will allow redirects back once the off-site portion of the flow is complete.

Copy the entire string from the input in the Charge > Connect settings and add it to your Stripe account settings. It'll be something of the form http://craft.dev/index.php?p=actions/charge/connect/oauthCallback

Configuring for Multiple Environments No problem! You simply need to list each of the possible callback endpoints, separated by a comma (,) in your stripe dashboard settings.

HTTPS Only in Production For security, stripe will only accept https callback urls when running a production platform. ie. when in live mode, you have to be calling back to https.

2. Add the Charge Connect Field #

All the account details are connected to Craft elements through the Charge_Connect fieldtype.

This fieldtype can be added to any Craft element that supports fields, but most commonly it'll be added to a User element, or maybe an Entry element, in a section like User Accounts.

Works on the Frontend, and the CP The connect fieldtype will work in both the Craft CP, and on front-end forms if you need it to. The output of the fieldtype will vary depending on the current connected state for an element.

When you've added the fieldtype to the appropriate element, that's it. If you want to, you could even have multiple connected accounts on a single element.

3. Update the Templates #

Now we have things configured, we just need to update our payment requests to know where they should be going.

Depending on your exact setup, this might vary slightly, but the key it to access the Charge_Connect fieldtype on the element that we setup in step 2.

Let's assume we're on a detail page for an entry with the fieldtype attached, and in this case, we've called that fieldtype connectedAccount. We'll assume we have the entry set as a variable called entry.

The all important value we want is {{ entry.connectedAccount.id }}. We'd reference this in our paymentOptions call like this:

{% set accountId = (entry.connectedAccount ? entry.connectedAccount.id : null ) %}

{% set options = {
    'planAmount' : 19.99,
    'accountId': accountId
%}

{{ craft.charge.setPaymentOptions(options) }}

That's it!

We might want to collect an application fee too. We can set that as either a hard value using applicationFeeInCents, or as a percentage of the total, with percentageFeeInPercent.

Let's collect a 10% fee on our payment:

{% set accountId = (entry.connectedAccount ? entry.connectedAccount.id : null ) %}

{% set options = {
    'planAmount' : 19.99,
    'accountId': accountId,
    'applicationFeeInPercent': 10
%}

{{ craft.charge.setPaymentOptions(options) }}

Simple as that!

We can also reference the details of a connected charge on the Charge model later, and access things like the connect account, connected account parent element, a formatted version of the collected fee and more.

4. Test #

Setting up Stripe connect has multiple moving parts, and extra config beyond the standard Charge stripe keys.

It's critically important to test things on each environment you'll be running this on, from end to end

You'll also need a different Stripe account to test with. Stripe will not allow you to test with the same account as the parent platform.

Connected in Live and Test When your Stripe account is in test mode, we can only connect accounts in test mode themselves. When in live we only connect in accounts to live mode. Be sure to re-connect your accounts and test in live mode when you change the base mode.