Integrations

Stripe

Credit partners for every paid Stripe invoice using customer metadata, handle refunds and pay partners through Stripe.

Payment tracking is available on every plan. Direct Stripe payouts are on Starter and above.

Connect Stripe under Integrations. We recommend a restricted key (rk_live_…) with only the permissions below; a secret key also works. Partner payouts also need Stripe Connect switched on in your account (Stripe dashboard > Connect > Get started): if it isn't, Intrio still connects and shows a reminder on Integrations and Payouts until it is. Intrio listens for invoice.paid, checkout.session.completed, checkout.session.async_payment_succeeded, charge.refunded, charge.refund.updated and transfer.reversed on your account, and account.updated for partners' connected accounts. Every event is signature-checked and processed once.

Restricted key permissions#

In Stripe, go to Developers > API keys > Create restricted key and set these. Everything else can stay at None.

Permissions

Accounts (Connect)Write
Check Connect is on, create each partner's Express account and read its payout status
Account Links (Connect)Write
Send partners to Stripe's hosted onboarding
Transfers (Connect)Write
Pay approved rewards from your balance to partners
CustomersWrite
Read customers on sales, and tag them with the referring partner so renewals stay attributed
ChargesRead
Match refunds to the original sale
RefundsRead
Reverse rewards for refunded sales
InvoicesRead
Link payments to invoices so subscription renewals credit the right partner
Webhook EndpointsWrite
Create the webhooks that tell Intrio about sales, refunds and partner accounts

Tag the customer#

Put the partner on the Stripe customer when you create it. Every paid invoice for that customer is then credited automatically.

Customer metadata

pp_refstring
Partner code. intrio_ref or via are also read, in that order.
pp_programmestring
Programme slug. Optional if the workspace has exactly one active Sign-ups or Sales programme.
pp_clickstring
Click id, optional. Applies the attribution window.
const customer = await stripe.customers.create({
  email: user.email,
  metadata: { pp_programme: "app", pp_ref: ref ?? "", pp_click: clickId ?? "" },
});

Using Stripe Checkout? Pass client_reference_id: intrio.clientReferenceId() (or pp_ref / pp_click / pp_programme in the session's metadata). On checkout.session.completed Intrio writes the partner onto the session's customer when it isn't tagged yet, so every later invoice is credited. Tag existing customers with stripe.customers.update.

What happens on invoice.paid#

  • Invoices with amount_paid of 0 are ignored.
  • The invoice is recorded as a payment with the invoice id as its id, the customer id as customer.id, and the paid date as occurred_at.
  • The first paid invoice credits the partner and wins the referral; each later invoice earns a reward until the programme's rewarded payments run out.
  • Customers with no partner in metadata are ignored, unless they were already credited.

What happens on checkout.session.completed#

  • Paid sessions (payment_status paid) in payment or subscription mode with a partner are recorded as a payment of amount_total. Unpaid and free sessions are ignored; delayed methods are credited on checkout.session.async_payment_succeeded.
  • The id is the session's invoice when it has one (subscriptions, or invoice creation), so invoice.paid for that invoice is a duplicate whichever arrives first. Otherwise it's the PaymentIntent id.
  • client_reference_id must be exactly intrio.clientReferenceId() (ref or ref:click); any other value is ignored.

Refunds#

On charge.refunded for a credited payment (an invoice or a Checkout payment), each succeeded Stripe refund is recorded once under its own refund id and amount, and the reward is reduced, voided or clawed back as described in rewards. Several partial refunds reverse exactly what was refunded. Pending refunds count when charge.refund.updated reports them succeeded.

Introductions billed in Stripe#

For Introductions programmes, link a Stripe invoice id to a won referral's invoice line. When Stripe reports it paid, the line is marked paid and its reward unlocks.

Payouts#

See payouts.

Last updated 20 November 2026. Building with an AI assistant? Point it at /docs/llms-full.txt.