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.
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.
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.
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.
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.
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.
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.
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