SaaSquatch Help Center

Referral SaaSquatch's Braintree integration uses Braintree's API and Braintree's Custom Fields to automatically track subscriptions and give discounts. This guide will walk you through how to set up this integration.

🔗 How to Configure Braintree

Before installing Referral SaaSquatch there are a few things that you need to configure manually in Braintree.

Test mode vs. live mode - Your Referral SaaSquatch program provides both a live and test mode. This test mode can be used in conjuction with Braintree Sandbox to test payments, subscriptions, and adding user before deploying to your production environment.

🔗 Set up a Braintree Custom Field and Discount

We use Braintree's Custom Fields to track when someone uses a referral code and Braintree's Discounts to apply referral discounts. These fields need to be set up in Braintree before turning on the referral program.

  1. Login to Braintree and go to Settings -> Processing.

    Add a custom field with:

    • API name saasquatch_coupon
    • Store and Pass Back to true

  2. Go to Recurring Billing -> Add-ons / Discounts on the left-hand menu and
    Add a discount with:
    • ID saasquatch_discount,
    • Name Saasquatch Discount,
    • Amount set to placeholder value of 1.00
    • Leave the duration as For Duration of Subscription

🔗 Add your Braintree API Keys in the SaaSquatch Portal

We connect to the Braintree API using your Braintree API keys. This allows us to automatically apply discounts to users' accounts.

  1. Login to Braintree and go to Account -> My User then scroll down and open "API Keys" under Authorization. Copy the "Merchant ID", "Public Key" and "Private Key".
  2. Login to Referral SaaSquatch and go to "Install" and click "Authorize". Paste in the "Merchant ID", "Public Key" and "Private Key" that you just copied, and press connect.

🔗 Add SaaSquatch to your Braintree webhooks

We use Braintree webhooks to determine when referral discounts should be made, updated, or ended.

  1. Login to Referral SaaSquatch and go to "Install" and copy the "Webhook URL".
  2. Login to Braintree and go to Settings -> Webhooks.
  3. Click "Create a webhook" if you have no existing webhooks or "New Webhook" otherwise.
  4. Paste the SaaSquatch "Webhook URL", check the box for all available Subscription notifications, and click "Create Webhook".

Note: If you don't have webhooks, sign in as an admin. Then go to "Settings" -> "Users and Roles" -> "Manage Roles". Click your role, enable "Manage Webhooks (Add/Edit/Delete)" and press "Save".

Repeat this process for both your test and live accounts. Tired of all the clicking? Help us reduce the manually configuration work here by encouraging Braintree to support Oauth apps and RestHooks.

🔗 How to Connect referrals with the SaaSquatch API

On your payment page you'll need to add an extra input element that accepts a referral_code and pass it to us via the REST API after the payment information has been successfully added to your customer in Braintree.

  1. Add a referral_code field to your payment form. You can show it to your users so that they can type in their friend's codes, or it can just be a hidden input field on the page.
    <input type="hidden" name="referral_code" />
  2. Use Squatch.js Autofill to read the referral cookie and set the value in the form input you just created.
    _sqh.push(["autofill", "name=referral_code"]);
  3. On your server, lookup the coupon information to include in your Braintree Subscription call using the SaaSquatch REST API.

    $ curl{TENANT_ALIAS}/code/{REFERRAL_CODE} \
    -u API_KEY: \
    -H "Content-Type: application/json"

    This step is important because it ensures that new customers will receive their discount immediately. If this step is left out then the referral discount will be applied as a refund to the first transaction at a later time. Referrers get credit on their next bill.

  4. Create a new subscription for your new customer. Use the discountId from SaaSquatch and remember to use discountPercentage to calculate the amount.

    result = Braintree::Subscription.create(
     :payment_method_token => "the_payment_method_token",
     :plan_id => "the_plan_id",
     :discounts => {
     :add => [{
         :inherited_from_id => "saasquatch_discount", // The `discountId` 
         :amount =>"25.00") // Calculated from `discountPercentage`
  5. On your server, after the Braintree customer has been created, POST the coupon code and the brand new paymentProviderId to the SaaSquatch REST API.

    curl -X POST{tenant_alias}/discount \
    -u :API_KEY \
    -H "Content-Type: application/json" \
    -d '{
     "accountId": "abc123",
     "paymentProviderId": "cus_123",
     "couponCode": "BOBTESTERSON"

    This step ensures that we can apply referral credit to a new user right away.

For Proration - If you're using subscriptions with automatic proration and you change the subscription price, you will need to recalculate the discount during upgrades and downgrades. You need to apply the result to the subscription before the prorated charges go through. If this step is left out then the prorated charge will have the existing discount subtracted from it and the new discount amount will be applied to the upcoming bill.


For Transparent Redirects When you're setting up your payment forms use customer[custom_fields][saasquatch_coupon] instead of referral_code in your forms and read this Braintree article about custom fields.

🔗 That's it!

Check out our Common Pitfalls Guide