# Referrals with Chargebee

A webhook protected by Basic auth Bolt Claw makes, because Chargebee signs nothing: payments, renewals and refunds.

Connect Chargebee and every successful payment, renewal and refund reaches the
program, credited to the partner whose link brought the customer.

**Weaker than a signature, said plainly.** Chargebee cannot sign its webhooks:
it can only protect them with Basic auth. Bolt Claw makes a random username and
password, keeps only the password's hash, and checks both on every delivery.
Keep them private, and make new ones on the card if they ever leak: the old
ones stop working at once.

## Add a webhook

1. Open the program, **Setup**, **Billing**, **Chargebee**. Bolt Claw makes a
   **username and password** and shows the password **once**: copy both now, with
   the endpoint URL.
2. In Chargebee: **Settings**, **Configure Chargebee**, **API Keys and Webhooks**,
   **Webhooks**, **Add Webhook**. Paste the URL, turn on **Protect webhook URL
   with basic authentication**, and enter the username and password. Select
   `payment_succeeded` and `payment_refunded`.

Lost the password? **Make new ones** replaces both; enter them in Chargebee
straight away.

## Pass the referral

Set the code on the subscription's metadata from your server, or add a custom
field `cf_boltclaw_ref` to the drop-in checkout:

```js
await chargebee.subscription.create_with_items("acme-user-10442", {
  subscription_items: [{ item_price_id: "pro-monthly" }],
  meta_data: { boltclaw_ref: ref, boltclaw_customer_id: "acme-user-10442" },
});
```

The customer is your own id from the metadata, else `cf_boltclaw_customer_id`,
else Chargebee's customer id. A payment on a recurring invoice after the first
is a renewal.

## Refunds

Each refund counts its own amount, so a partial refund takes back that share of
the commission. Chargebee has no card-dispute event.

## Coupons

Chargebee's events name coupons by id only, so a coupon is not read: use partner
links or the referral field.

## Test mode

A Chargebee test site is its own site. Add a second Chargebee integration for it
and switch **Sandbox** on.

## 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 on your Chargebee test site. 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-chargebee 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. -->