# Referrals with FastSpring

A webhook with an HMAC secret and Expansion on: orders, subscription charges, returns and chargebacks.

Connect FastSpring and every completed order, subscription charge, return and
chargeback reaches the program, credited to the partner whose link or coupon
brought the customer.

## Add a webhook

1. Open the program, **Setup**, **Billing**, **FastSpring**, and copy the
   endpoint URL.
2. In FastSpring: **Developer Tools**, **Webhooks**, **Configuration**, **Add
   Webhook**. Turn **Webhook Expansion** on (without it, events carry ids only),
   add the URL, set an **HMAC SHA256 Secret**, and select `order.completed`,
   `subscription.charge.completed`, `return.created` and `chargeback.created`.
3. Paste the same secret on the card.

FastSpring signs each delivery with no timestamp and may send several events in
one; each event's own id is what keeps it from counting twice.

## Pass the referral to checkout

Tag the session with the code:

```js
fastspring.builder.tag({
  boltclaw_ref: BoltClawReferral.code(),
  boltclaw_customer_id: "acme-user-10442",
});
```

The customer is your own id from the tags, else FastSpring's account id.

## Returns and chargebacks

A return takes back the returned share of the commission; a chargeback reverses
the sale in full.

## Coupons

A coupon arrives as its code, so an order made with a partner's coupon alone is
credited to them.

## Test mode

FastSpring says whether each event is live. A test order is recorded as test
data.

## Check it works

On the program's **Setup** tab, the **Billing** row of the setup status turns
`Connected` with the first verified event, and says when a delivery was refused
(nearly always the wrong secret). Then press **Send a test sale** to see a
click, a signup, a sale and a refund go through your rules with test data, or
make a real test purchase with a FastSpring test order. See [Connect your billing system](https://boltclaw.ai/docs/referral-setup)
for the whole setup status and what test data never does.

<!-- https://boltclaw.ai/docs/referral-billing-fastspring as markdown. Generated from openapi.yaml; API version 1.22.0. -->
<!-- Every /docs page answers as markdown: add .md to its path, or send Accept: text/markdown. -->