Braintree Install Guide

---

🔗 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](/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 <a href="/squatchjs#autofill">Squatch.js Autofill</a> to read the referral cookie and set the value in the form input you just created.
```js
_sqh.push(["autofill", "name=referral_code"]);```
3. On your server, <a href="/api/methods#get_coupon">lookup the coupon information</a> to include in your Braintree Subscription call using the SaaSquatch REST API.
```curl 
$ curl https://app.referralsaasquatch.com/api/v1/{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 => BigDecimal.new("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 https://app.referralsaasquatch.com/api/v1/{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.

GET https://app.referralsaasquatch.com/api/v1/{TENANT_ALIAS}/account/{ACCOUNT_ID}/reward

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