Stripe

Connect Stripe so invoices, payments, refunds, and subscriptions become RefRef facts, and deliver credit, promotion codes, and plan upgrades in Stripe.

The Stripe integration works in two directions:

  • Facts in. Paid invoices, one-time payments, refunds, lost disputes, and subscriptions become purchase Events, purchase adjustments, and Subscription facts in your Project. Your server does not send them to the RefRef API.
  • Rewards out. RefRef delivers a Program's account credit to the customer's Stripe balance, its discounts as single-use promotion codes for that customer, and its custom Rewards as a free plan upgrade.

You connect one Stripe account to each Project. A Sandbox Project connects with a test-mode key, and a Live Project with a live-mode key. Start in the Sandbox Project.

Connect Stripe

  1. In Stripe, create a secret key or a restricted key in the mode of the Project (test mode for a Sandbox Project). A restricted key needs write access to Customers, Coupons, and Promotion codes, and read access to Invoices, Invoice payments, PaymentIntents, Checkout Sessions, Subscriptions, and Events. In test mode it also needs read access to Test clocks.

  2. In RefRef, open the Project's Settings → Integrations, choose Stripe, paste the key, and select Connect. RefRef checks the key with Stripe and stores it encrypted. A key of the other mode is refused.

    Connect Stripe in the Integrations settings of a Sandbox Project

  3. The connection shows its webhook URL, which ends in /integrations/v1/stripe/webhooks/<connectionId>. Copy it.

  4. In Stripe, add a webhook endpoint with that URL, in the same mode, with API version 2026-09-30.endive, and subscribe it to these events:

    Stripe eventWhat RefRef records
    invoice.paidA purchase Event of the invoice
    payment_intent.succeededA purchase Event of a one-time payment that paid no invoice
    refund.created, refund.updatedA refund purchase adjustment, once the refund has succeeded
    charge.dispute.closedA dispute_loss purchase adjustment, when the dispute is lost
    customer.subscription.created, customer.subscription.updated, customer.subscription.deletedThe start of the Subscription, and its end when Stripe ends it
    customer.subscription.paused, customer.subscription.resumedA pause and a resume
    customer.discount.createdA RefRef discount code that a checkout used
  5. Copy the endpoint's signing secret (whsec_…), paste it into the connection's Signing secret field in RefRef, and select Save. Until you save it, RefRef refuses the endpoint's events.

    The webhook URL and the signing secret of a Stripe connection

RefRef checks the Stripe-Signature of each event and refuses a changed body, a timestamp more than five minutes old, or another secret. A repeated event is stored once. Each event carries Stripe's livemode: a Sandbox Project ignores live events, and a Live Project ignores test events.

Name the customer at checkout

RefRef never matches a Stripe customer by email. Your server names the participant in the metadata of the Subscription or of the one-time PaymentIntent:

Metadata keyValue
refref_external_idThe participant's externalId in the Project, for example your user ID. Required.
refref_participant_kindindividual (the default) or group, for a team account. Another value names nobody.
refref_handleOptional. The value of the buyer's refref_handle cookie, from the landing script. See Buyers who did not sign up first.

With Stripe Checkout, put the keys in subscription_data.metadata for a subscription and in payment_intent_data.metadata for a one-time payment:

Create a Checkout Session on your server
const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: "price_…", quantity: 1 }],
  subscription_data: {
    metadata: {
      refref_external_id: user.id,
      // Optional: the buyer's browser, for a buyer who did not sign up first.
      ...(request.cookies.refref_handle && {
        refref_handle: request.cookies.refref_handle,
      }),
    },
  },
  success_url: "https://example.com/thanks",
});

Stripe copies the Subscription's metadata into each of its invoices, so renewals carry it. The metadata of the Checkout Session itself and of the customer does not count. A payment or Subscription without refref_external_id gives no fact.

Buyers who did not sign up first

A buyer who clicked a referral link and then paid, with no earlier signup, has no identified browser yet. Read the buyer's refref_handle cookie and put its value into the same metadata (subscription_data.metadata or payment_intent_data.metadata) as refref_handle, next to refref_external_id. At the participant's first fact, RefRef identifies that browser to the participant, so the referral click counts.

  • RefRef uses the handle only when the participant has no Event yet, and only when the handle is open and belongs to the Project. A handle that a signup already identified changes nothing.
  • The first fact is the moment of identification: the start of the subscription, or the one-time payment. A click counts when it is at most 90 days before it.
  • A buyer without the cookie, or a checkout without refref_handle, is attributed only through a referral the participant already has.

Referral codes at checkout

A buyer can enter a referral code at a Stripe checkout instead of clicking a link. Create a Stripe promotion code whose code is exactly the referrer's referral code, with the same upper and lower case, for example JANE20, and allow promotion codes in the Checkout Session (allow_promotion_codes: true).

When a one-time payment redeems such a code, RefRef puts it on the purchase Event as its referral code. It reads the code from Stripe: the promotion code that the payment's Checkout Session or the invoice redeemed. A code in the metadata does not count. A redeemed code that is not a live referral code of the Project, or that is the buyer's own, changes nothing.

A referral code at a subscription checkout is not credited yet. A subscription's referral is decided when it starts, and the start carries no referral code. Use a referral link, or refref_handle, for subscriptions.

What RefRef does with the facts

  • First purchase. A billing fact carries no browser data. The start of the Subscription uses the referral that the participant already has, for example from a signup that identified the browser. When the participant has no referral yet and purchase is a qualifying event type, the fact can create one from a click in a browser that your backend identified to the participant before, or that the checkout named with refref_handle. Its invoices get the referral as their attribution.
  • Renewals and trials. Each later invoice of the Subscription, such as the first invoice after a trial or a renewal, inherits the Subscription's referral without a new click, also after the attribution window. A Program rule that pays on each purchase earns a Reward on each paid invoice.
  • Paid history. Before RefRef evaluates a purchase Reward, it reads the referee's paid invoices and one-time payments between the referral and the purchase, so that a "first purchase" rule counts only a first purchase.
  • Refunds and disputes. A refund or a lost dispute reduces the purchase by its share of the payment. Rewards calculated from that purchase get a matching adjustment. When the purchase is fully refunded, RefRef takes back a Reward that it already delivered: it debits the credit or deactivates the promotion code. A partial refund leaves a delivered Reward in place.
  • Missed events. Every five minutes RefRef reads the recent Stripe events of these types (Stripe keeps them for 30 days) and records any fact that a webhook did not bring.

Deliver Rewards in Stripe

In the Program's settings, open Delivery and choose Stripe for the Reward kinds that you want RefRef to deliver:

The Delivery settings of a Program connected to Stripe

RewardDelivery in Stripe
Account creditA credit on the customer's balance (USD, EUR, GBP, CAD, or AUD). Stripe applies the balance to the customer's next invoices in that currency. A void debits it back.
DiscountA coupon for one redemption and a promotion code that only that customer can use, for the rule's duration: one invoice, the rule's number of months, or every invoice. If the customer has one active or trialing subscription, RefRef also applies the code to it, from the next invoice. A void removes the discount and deactivates the code.
CustomA free upgrade to a higher plan for a number of billing periods. See Give a free plan upgrade.

RefRef delivers to the Stripe customer of the beneficiary. It learns the customer from the beneficiary's own invoices and payments; for a referrer who has not paid through Stripe, send the customer ID as billingIds.stripe with PUT /v1/participants. A Reward whose beneficiary has no Stripe customer yet waits.

A delivery is Stripe's success answer. RefRef does not read whether the customer later used the credit. It records when a discount code is used: at once when RefRef applies it to the subscription, or later from customer.discount.created.

Apply a discount at checkout

A discount that RefRef could not apply to a subscription, for example a referred friend's discount before the first payment, waits for the friend's checkout. The Widget shows the friend the code to enter. You can also apply it for them:

  1. Create the Stripe customer when the friend signs up, and send it as billingIds.stripe with PUT /v1/participants. RefRef then delivers the discount within seconds.
  2. When you create the Checkout Session, read the friend's delivered discount: GET /v1/rewards?projectId=…&beneficiaryExternalId=…&benefitKind=discount&fulfillmentStatus=fulfilled, and take the Reward whose beneficiaryRole is referee.
  3. If its delivery.appliedAt is null, pass discounts: [{ promotion_code: delivery.providerReference }] and the same customer to the Checkout Session. The code works only for that customer, once.

Not available: payouts to referrers through Stripe.

Give a free plan upgrade

A custom Reward can move the customer to a higher plan for a number of billing periods. The customer keeps paying the price of the current plan, and then goes back to it automatically.

Set it up

  1. In the Project's Settings → Custom units, add a unit for the upgrade, for example "Pro month".
  2. In the Program's rules, give that unit as a custom Reward with a quantity of 1. A plan upgrade refuses another quantity.
  3. In the Program's Delivery settings, choose Upgrade the plan in Stripe for custom Rewards. Under Plan upgrades, enter for the unit the Stripe price ID (price_…) of the higher plan and the number of billing periods, from 1 to 12. A unit without a plan goes through your product (webhook).

The plan upgrade settings of a Program connected to Stripe

With a restricted key, a plan upgrade also needs write access to Subscriptions and Subscription schedules, and read access to Prices.

What the customer gets

RefRef puts the customer's subscription under a Stripe subscription schedule:

  1. At once, the subscription moves to the higher price, with no charge and no proration. The rest of the current billing period on the higher plan is free.
  2. The next N renewals get a fixed-amount coupon of the price difference, so each of them bills the customer's current price.
  3. At renewal N+1, Stripe moves the subscription back to the current price without the coupon. Stripe does this from the schedule, also when RefRef is not available. RefRef then releases the schedule.

While the schedule runs, change the customer's plan through the schedule, or release the schedule first. If the subscription moved to another price or left the schedule, or if it ended, RefRef records this at the switch back and changes nothing.

When RefRef does not upgrade

RefRef changes nothing, and the Reward waits for you with the reason, when:

  • The customer has no active subscription (a trial, a past-due or paused subscription, or one set to cancel does not count), or has more than one.
  • The subscription, its item, or the customer already has a discount.
  • The price that you set is not higher than the current price.
  • The two prices have a different currency or billing interval.

The delivery also fails, for you to resolve, when the subscription has more than one item, when another subscription schedule manages it, when its trial has not ended, or when a price is tiered or metered.

A void before the switch back moves the subscription back to the current price at once, with no charge.

A connection made before plan upgrades

A Stripe connection made before plan upgrades were available does not offer Upgrade the plan in Stripe. In Settings → Integrations, select Test connection on the Stripe connection. After the test passes, the option is available.

Test the integration

  1. Connect a test-mode key to your Sandbox Project and add the webhook endpoint in test mode.
  2. Create a referral link for a participant. Open it in a browser on a page with the landing script, and sign up there, so that your backend identifies the browser with the signup.
  3. Create a Subscription with the metadata and pay it with a Stripe test card or test payment method.
  4. In the Sandbox Project, check Referrals and Rewards. A Reward that RefRef delivered through Stripe shows its Stripe reference.
  5. Refund the payment in Stripe and check the adjustment on the Reward.

RefRef does not evaluate a fact dated in the future. An invoice of a Stripe test clock that you advanced past today waits until that date.

On this page