# Referrals with Whop

A webhook signed with Standard Webhooks: payments, refunds and disputes, with promo codes credited from their text.

Connect Whop and every payment, refund and dispute reaches the program,
credited to the partner whose link or code brought the customer. Whop signs
deliveries with Standard Webhooks, within a five-minute window.

## Add a webhook

1. Open the program, **Setup**, **Billing**, **Whop**, and copy the endpoint URL.
2. In Whop: **Developer**, **Webhooks**, **Create webhook**. Paste the URL and
   select `payment.succeeded`, `refund.created`, `refund.updated` and
   `dispute.created`.
3. Paste the webhook's secret (it starts `ws_`) on the card.

## Pass the referral to checkout

Set `metadata.boltclaw_ref` when you create the checkout configuration.

```js
await whop.checkoutConfigurations.create({
  plan_id: "plan_monthly",
  metadata: { boltclaw_ref: ref, boltclaw_customer_id: "acme-user-10442" },
});
```

The customer is your own id from the metadata, else the Whop user, else the
membership. Whop reports amounts in major units; they are converted exactly to
the currency's minor units.

## Refunds and disputes

Each refund counts once Whop says it succeeded, for its own amount. A dispute
reverses the sale in full.

## Discount codes

A promo code arrives as its text, so a payment made with a partner's code alone
is credited to them.

## Test mode

Whop's events do not say they are tests. For a test store, add a second Whop
integration 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. 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-whop 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. -->