Skip to content

Refexa documentation

How Refexa connects affiliate referrals to Stripe revenue: which billing flows it tracks, how a customer is credited to an affiliate, the one server-side API call you make, and what happens to commission when a payment is refunded or disputed.

How Refexa fits together

Refexa is affiliate and referral tracking for SaaS that bills through Stripe. Your product keeps billing exactly as it does today. Refexa records which affiliate referred each customer, the commission their payments earn, and the payouts you make. It is a ledger and a reporting tool: it never holds or moves your money or your affiliates' money.

  1. 01

    Create your program

    Choose a commission percentage, first payment or recurring, an optional duration in months, and where referral links land. Affiliates apply on your public program page with a magic link, and you approve them. Each approved affiliate gets a referral link.

  2. 02

    Connect Stripe

    Install the Refexa Stripe App with read-only access. Refexa reads the payment, refund and dispute events it needs. It cannot create charges, refunds, subscriptions, transfers or payouts.

  3. 03

    Create a server key

    On your Integration page, create a test key for test customers and a live key for live ones. Test and live customers are kept separate, so testing never decides who is credited in live. Each key is shown once. Keep it on your server.

  4. 04

    Keep the visitor token

    A referral click lands on your site with rfx_vid in the URL. Save it on your own domain until the visitor signs up.

  5. 05

    Bind the customer

    When your server creates the customer record, call the bind API once with your own customer ID and the saved token. Link the Stripe customer in the same call, or in a later one.

  6. 06

    Test, then go live

    Check the whole flow with Stripe test mode first. When you are ready for real customers, connect live Stripe on your Integration page and switch your production server to the live key. Your test setup stays as it is, and the live setup card confirms when both are in place.

  7. 07

    Pay affiliates and record it

    Paid invoices and Checkout payments become commission, payable 30 days after the payment. You pay affiliates yourself, then record the payout in Refexa.

The exact Refexa address, helper script and server keys for your workspace are on your Integration page after you sign up. Examples below write that address as REFEXA_ORIGIN.

Still deciding whether Refexa fits your billing? Read the overview of Refexa for Stripe-based SaaS.

Supported Stripe billing

Refexa is built around the standard SaaS flows on Stripe. It reads them through a read-only Stripe App connection and turns each collected payment into exactly one record, however many Stripe events report it.

Supported

  • Stripe Billing subscriptions

    Subscription invoices that Stripe charges automatically, including renewals.

  • Stripe Checkout, subscription mode

    Subscriptions started from a Checkout Session. The invoices they produce are tracked like any other subscription.

  • Stripe Checkout, payment mode

    One-time payments taken through a Checkout Session that has a Stripe customer. Stripe does not create one by default in payment mode, so pass an existing customer or set customer_creation to always.

  • Refunds

    Full and partial refunds of those payments, including refunds issued through a credit note.

  • Disputes

    Funds withdrawn for a dispute, and funds returned when a dispute is won.

What counts as revenue

Commission follows money that was actually collected, not plan value. A completed Checkout Session on its own is not revenue; the payment it collects is. Revenue is measured after discounts and credits, excluding tax, and before payment-processor fees. Dispute fees and processor fees are never counted. Amounts stay exact, in integer minor units of the currency your customer paid in, and are never converted.

Not supported

  • Direct PaymentIntent or Payment Element integrations that do not use Stripe Checkout.
  • One-time Checkout payments without a Stripe customer, which is what Stripe does by default in payment mode.
  • Checkout payments that include a shipping amount.
  • Invoices sent for manual payment (Stripe invoices with the send invoice collection method).
  • Invoices settled from a customer credit balance.
  • Any other Stripe flow Refexa cannot interpret exactly.

A payment Refexa cannot interpret is recorded as unsupported, with a reason. It earns no commission and carries no Refexa fee. Refexa does not guess a number for it. Founders see every recorded payment, with its status and reason, under Integration, Stripe payments.

Referral attribution

Attribution decides which affiliate, if any, is credited with a customer. Refexa makes that decision once, from recorded referral clicks, at the moment your server binds the customer.

Referral click
An affiliate shares their referral link. A click records the visit and sends the visitor to your site with a visitor token, rfx_vid, in the URL. Clicks Refexa recognizes as automated, such as known crawlers and link previews, still redirect but never win attribution.
Last touch, 60 days
At the first bind, the most recent eligible click carrying that visitor token wins. A click is eligible if it happened at or before the bind and no more than 60 days (60 x 24 hours) earlier. Ties are broken the same way every time.
First bind decides
Only the first bind for a customerRef can look at referral clicks. Every later call returns the same answer. A click that happens after the first bind never moves the credit.
Test and live are separate
Test and live customers are kept apart. The same customerRef can exist once in test and once in live, and each has its own first bind, attribution and history. A test bind can never decide, block or change who is credited for live revenue, and test customers never earn commission or appear to affiliates.
Deterministic
The same customer, token and clicks always produce the same result. Your server cannot name an affiliate: the bind API only accepts the opaque visitor token, and Refexa chooses the winner from its own records.
No referral
If the first bind sends no visitor token, or no eligible click exists, the customer is recorded as not referred. That is final for automatic attribution: a later bind with a token does not change it.
Self-referral protection
If you send customerEmail and it matches the email of the affiliate who would be credited, the credit is refused. The check can only compare the email you send with the affiliate's account email. Without customerEmail, Refexa cannot run this check, and attribution follows the click as usual.
Manual changes
You can attribute a customer manually, reassign one, or remove an attribution from your dashboard. Each change needs a reason and is kept in the history; nothing is overwritten.
Removal is final
A removed attribution never comes back automatically, whatever later binds send. Only a new manual attribution by you can credit that customer again.
Payments before the click
A payment made before the referral click that won attribution (or before a manual attribution was created) never earns that affiliate commission. Later eligible payments still can.
Revoked links
Revoking a link or an affiliate stops new clicks from being recorded. Clicks already recorded stay eligible until they fall outside the 60-day window.

Keeping the visitor token

A referral click arrives on your landing page with ref (the referral link token) and rfx_vid (the visitor token) in the URL. Only rfx_vid matters for attribution. Keep it until you bind the customer.

Example landing URL

https://your-app.example/signup?ref=<referral-token>&rfx_vid=<43-character-token>

Option 1: the Refexa helper script

Add the optional helper to your landing pages. It saves a valid rfx_vid in a first-party cookie on your own domain, and with data-clean-url="true" removes ref and rfx_vid from the address bar. Read the token back on your server from the rfx_vid cookie, or in the browser with window.Refexa.visitorToken(). Set data-cookie-domain to share the cookie across your subdomains.

<script src="${REFEXA_ORIGIN}/rfx/v1.js" data-clean-url="true"></script>

The helper calls no Refexa endpoint, sends no email or customer data, and creates no identifier of its own. A malformed token in the URL is ignored.

Option 2: capture it yourself

Read rfx_vid from the landing URL and store it wherever you keep session state. A cookie set by your own server usually lasts longer than one written by JavaScript.

Customer bind API

One server-to-server call connects a visitor to your durable customer record and, when it exists, to the Stripe customer. Call it when your server creates the customer.

POST ${REFEXA_ORIGIN}/api/v1/customers/bind

Authentication

Send your server key as Authorization: Bearer <server key> with a JSON body. The key identifies your workspace and one Stripe mode: a test key binds test customers, a live key binds live ones. Test and live customers are separate, so the same customerRef bound with each key is two customers with two independent first binds, and the response's livemode says which one you bound. Never put a server key in browser JavaScript, a mobile app or client-visible configuration. If one is exposed, revoke it on your Integration page and create another.

Request body

customerRefstring · Required
Your own immutable customer ID, up to 255 characters. Use the ID your database already keys the customer on, never an email address or username. Every later call for this customer must send the same value. It is unique per Stripe mode: the server key's mode decides whether this is a test customer or a live customer, and the same customerRef may exist once in each.
visitorTokenstring or null · Optional
The rfx_vid value your site saved from the referral landing URL. Send it on the first bind. A supplied value that is not a valid Refexa visitor token is rejected.
customerEmailstring or null · Optional
The customer email you have on record. Used only to check the selected affiliate for a self-referral. It never decides which affiliate is credited, and Refexa does not store the address.
stripeCustomerIdstring or null · Optional
The Stripe customer ID (cus_...) for this customer. Refexa looks it up in your connected Stripe account before linking it. Omit it if the Stripe customer does not exist yet and call again later.
stripeLivemodeboolean · Optional
The Stripe customer's mode. Send it with stripeCustomerId. It is a check, not a choice: it must match the server key's mode, which is what decides the mode. Test keys bind test customers, live keys bind live customers.

Example request body (fake values)

{
  "customerRef": "user_8f3a21",
  "visitorToken": "example_visitor_token_not_real_000000000000",
  "customerEmail": "customer@example.com",
  "stripeCustomerId": "cus_EXAMPLE000000",
  "stripeLivemode": false
}

Example call

// On your server, when you create the customer record.
const response = await fetch(`${REFEXA_ORIGIN}/api/v1/customers/bind`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.REFEXA_SERVER_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customerRef: user.id, // your own immutable customer ID
    visitorToken: rfxVidFromYourCookie ?? null,
    customerEmail: user.email, // optional, used only for self-referral protection
    stripeCustomerId: stripeCustomer.id, // optional, when the Stripe customer exists
    stripeLivemode: stripeCustomer.livemode,
  }),
})
const result = await response.json()
if (!response.ok) throw new Error(`Refexa bind failed: ${result.error} (${result.code})`)
if (result.stripeCustomer.linked !== true) throw new Error('Stripe customer not linked')

Response

A successful call returns HTTP 200 with one of four outcomes. Every response, success or error, has an x-request-id header.

outcome
One of the four outcomes below. All four are HTTP 200.
customerId
Refexa's ID for this customer. The same on every call with the same customerRef in the same mode; a test customer and a live customer with the same customerRef have different IDs.
livemode
The mode of the customer that was bound: false for a test customer, true for a live customer. Always the server key's mode.
referral.evaluated
true only when this call was the first bind of this customerRef in this mode and checked referral clicks. Always false on later calls in the same mode.
attribution
null, or the attribution: its id, the credited programAffiliateId, boundAt, attributionWindowDays (60), rule (last_touch) and selfReferralChecked (false means the check did not run, not that it passed).
stripeCustomer.linked
true when a verified Stripe customer is linked to this customer in the key's mode, including on a repeat call that sends no stripeCustomerId.
stripeCustomer.livemode
The linked mode when linked, otherwise null.

Example response (fake values)

{
  "outcome": "attributed",
  "customerId": "00000000-0000-4000-8000-000000000001",
  "livemode": false,
  "referral": {
    "evaluated": true
  },
  "attribution": {
    "id": "00000000-0000-4000-8000-000000000002",
    "programAffiliateId": "00000000-0000-4000-8000-000000000003",
    "boundAt": "2026-01-15T10:30:00.000Z",
    "attributionWindowDays": 60,
    "rule": "last_touch",
    "selfReferralChecked": true
  },
  "stripeCustomer": {
    "linked": true,
    "livemode": false
  }
}
attributed
First bind of this customerRef in this mode. An eligible referral click was found and the customer is now credited to that affiliate.
already_bound
The customer already has an attribution. It is returned unchanged; later clicks are not considered.
no_eligible_referral
No attribution. On a first bind: no visitor token was sent, or no eligible click was found within 60 days. On a later call in the same mode: the first bind found none, or the attribution was removed.
self_referral_blocked
The customer email matched the selected affiliate's email, so the credit was refused.

Attribution and Stripe linkage are separate facts. outcome: "attributed" does not mean Stripe revenue is linked: check stripeCustomer.linked === true.

Repeat calls are safe

Calls are keyed on customerRef, so retrying the same call never creates a second customer or a second attribution. The first bind is the only one that evaluates referral clicks; repeats return the same attribution (or the same refusal) and may add or refresh the Stripe link. Linking the same Stripe customer again succeeds. No idempotency header is needed.

When the Stripe customer exists later

If Stripe creates the customer after signup, for example at the end of Checkout, bind the visitor first and call again from your server-side Stripe or Checkout completion flow with the same customerRef. bindRefexaCustomer below is your own wrapper around the call above.

// 1. At signup, before a Stripe customer exists:
await bindRefexaCustomer({
  customerRef: user.id,
  visitorToken: rfxVidFromYourCookie ?? null,
})

// 2. Later, on your server, once Stripe has created the customer:
const linked = await bindRefexaCustomer({
  customerRef: user.id, // the same immutable ID
  stripeCustomerId: stripeCustomer.id,
  stripeLivemode: stripeCustomer.livemode,
})
if (linked.stripeCustomer.linked !== true) throw new Error('Stripe customer not linked')

One-time Checkout needs a Stripe customer

In payment mode, Stripe Checkout creates no customer unless you ask for one, and Refexa matches a payment only through a Stripe customer you have linked. Create every payment-mode Checkout Session on your server with a customer: pass the Stripe customer already linked to this customerRef, or set customer_creation to always when the buyer has none yet, then link the new customer after payment. A customerRef can be linked to only one Stripe customer in each mode, so do not create a second one for a returning buyer: that payment could never be matched.

// 1. Create the payment-mode Checkout Session on your server, always with a customer.
const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [{ price: 'price_EXAMPLE', quantity: 1 }],
  success_url: 'https://example.com/thanks',
  ...(user.stripeCustomerId
    ? { customer: user.stripeCustomerId } // the customer already linked to this customerRef
    : { customer_creation: 'always' }), // first purchase: Stripe creates the customer
})

// 2. After payment, on your server (for example in your checkout.session.completed
//    handler), link the customer. Linking the same customer again is safe.
const linked = await bindRefexaCustomer({
  customerRef: user.id, // the same immutable ID
  stripeCustomerId: completedSession.customer,
  stripeLivemode: completedSession.livemode,
})
if (linked.stripeCustomer.linked !== true) throw new Error('Stripe customer not linked')

Refexa never identifies a customer from client_reference_id, metadata or the email entered in Checkout. A payment-mode Checkout payment without a Stripe customer is recorded as unsupported. It earns no commission and carries no Refexa fee.

Errors

Error bodies carry error, a more specific code, a fixed safe message, param when one field is at fault, and request_id. They never include Stripe payloads, tokens or account identifiers.

Example error (fake values)

{
  "error": "invalid_request",
  "code": "field_invalid",
  "message": "customerRef must be a string",
  "param": "customerRef",
  "request_id": "00000000-0000-4000-8000-0000000000aa"
}
400 invalid_requestjson_required, field_invalid
The body is not a JSON object, or a field is missing, has the wrong type or is malformed. param names the field when known.
401 unauthorizedkey_missing, key_invalid
No Authorization header, or the server key is unknown or revoked.
403 forbiddenstripe_mode_mismatch
stripeLivemode does not match the server key's mode. Nothing is read or written.
409 stripe_customer_conflictstripe_customer_linked_elsewhere, customer_has_other_stripe_customer
The Stripe customer is already linked to a different customerRef, or this customerRef already has a different Stripe customer in this mode.
422 stripe_customer_unverifiedstripe_customer_id_invalid, stripe_customer_not_found, stripe_not_connected, stripe_connection_attention_required
The Stripe customer ID is malformed, missing, deleted or in the other mode, or your Stripe connection is missing or needs reconnecting. Nothing is bound.
503 stripe_unavailablestripe_timeout, stripe_network, stripe_provider_unavailable, stripe_rate_limited, stripe_token_refresh_unavailable
Stripe could not be reached to verify the customer. The response carries Retry-After; retry the same call.
500 binding_failedinternal
An unexpected failure. Retry the same call; quote request_id if it persists.

Commission lifecycle

Commission is what you owe an affiliate. It is calculated from each supported payment by a bound, attributed customer, and moves through a few clear states.

Your rule
A commission percentage, either on the first payment only or recurring. A recurring rule can be lifetime or limited to a number of months, counted from when the customer was credited to the affiliate.
Changing your rule
You can change the rule in Settings at any time. Changes apply to future payments after the change, including payments from customers who were already referred. Already-earned commission does not change. A payment made before the change keeps the old rule, even if Stripe reports it later. Switching from recurring to first payment only is available until the first customer is credited to an affiliate.
Calculation
The percentage of the payment’s eligible revenue, in exact minor units, rounded half up, in the payment’s currency. Each commission records the rule it was calculated under, so later configuration never rewrites past commission.
First payment
A first-payment rule pays on one qualifying payment per customer. Payments that do not qualify, such as one made before the referral click, do not use it up.
Pending
New commission is pending. It cannot be paid yet.
Payable
Commission becomes payable 30 days after the customer’s payment.
Paid
You pay affiliates yourself, by bank transfer, PayPal, Wise or however you already pay, then record the payout in Refexa. A payout settles the oldest payable commission first and can be exported as CSV.

Commission and the Refexa fee are separate

Commission is owed to your affiliate, at the rate you choose. Refexa's own fee is 3% of the same affiliate-generated revenue, capped monthly per currency, and is never taken out of the commission. See pricing.

Refunds and disputes

Refexa never edits or deletes a past record. A refund or dispute adds a reversing entry next to the commission it affects, so the history always shows what happened and when.

Full refund
The commission for that payment is reversed.
Partial refund
The commission is reversed pro rata to the refunded amount. Several partial refunds never reverse more than the original commission.
Credit notes
A credit note that refunds money is handled through its refund, once. It is never counted twice.
Dispute
When Stripe withdraws funds for a dispute, the related commission is reversed, pro rata for a partial dispute.
Dispute won
When Stripe returns the disputed funds, the reversed commission is restored with a further entry.
After payout
If you already paid the commission, the payout record stays as it is. The reversed amount is carried forward and offset against that affiliate’s future commission.
Refexa fee
Refunded or disputed affiliate revenue reverses its Refexa fee too, in the month of the original payment.

Limits and unsupported flows

Refexa favors exact numbers over broad coverage. Where it cannot be exact, it says so instead of estimating.

Payment Links
Stripe Payment Links are not listed as supported. Do not rely on them for affiliate commission unless this page lists them.
Stripe history
Refexa does not import your past Stripe payments when you connect. Commission comes from customers you bind after setup.
Unlinked customers
Refexa never matches a payment to a customer by email, name or amount. A payment from a Stripe customer you never link is not attributed. Payments waiting for a link are counted on your Integration page.
Cookie lifetime
Refexa uses a 60-day attribution window where browser and platform conditions permit. Browser privacy controls can shorten how long a saved token lasts.
Cross-device
A visitor who clicks on one device and signs up on another is attributed only if your own system carries the token across. Refexa does no fingerprinting or identity guessing.

Refexa works with Stripe only. It does not pay affiliates for you, and it does not write to your Stripe account.

Privacy and security

  • Read-only Stripe access. Refexa cannot create charges, refunds, subscriptions, transfers or payouts in your account.
  • Refexa never holds or moves money. Affiliates are paid by you, outside Refexa.
  • Server keys stay on your server, are shown once and can be revoked at any time from your Integration page.
  • A click records the link, the visitor token, the time, the browser user agent, the referring site’s hostname and the landing path. No IP address is stored, and there is no fingerprinting.
  • customerEmail is used only for self-referral protection. Refexa does not store the address, and never uses email to find or credit an affiliate.
  • Bind API errors return fixed messages and never include Stripe payloads, tokens or account identifiers.
  • Affiliates see their own referral link and activity, never your other affiliates or your totals.
  • Every workspace is isolated. A server key only ever acts on its own workspace.

Connect Stripe, add one server-side bind, share your first link.

Create your program and test the whole flow in Stripe test mode before any real customer pays.

Launch your affiliate program