Prefer to hand this to a coding agent? Your program’s Tracking step and Settings → Store generate an Install Kit from this same contract. Both paths produce the same diagnostics and pass the same fixtures. Preserving a referral identifier is not automatic purchase tracking — a server or provider event is still required — and neither path generates a standalone partner portal, ledger or payout service.
Before you begin
You need permission to configure your Stripe integration, a saved Philos workspace, a program with reviewed terms, and access to a Stripe sandbox. The isolated installation test uses a fictional referral reference; it does not create a real partner or earning.
- Keep test and live configuration separate. Use the webhook signing secret for the exact endpoint and mode.
- Know where checkout is created in your application. A link click alone does not carry a referral into a server-created checkout.
- Confirm the currency and product scope your program accepts. The application must associate the purchase with the correct customer.
- Payment collection in your store is independent from how you pay partner rewards.
Connect the event source
- Open your program’s Tracking step or workspace Store settings. Use the tenant-specific Stripe ingest endpoint shown there.
- In live mode, add the Stripe webhook endpoint for
/api/ingest/<tenant-id>/stripe. After Stripe creates it, edit its URL to/api/ingest/<tenant-id>/stripe?account=<acct_…>&endpoint=<we_…>using your Stripe account id and that endpoint’s id; editing the URL keeps the same signing secret. - Enter that endpoint’s signing secret through Philos’s secure settings under Store → Live purchase events. Do not paste secrets into a chat or public page.
- Carry the captured referral reference through checkout. The existing adapter uses the Checkout Session’s
client_reference_idand Stripe customer association. A server may instead setmetadata.philos_codeto a saved partner code (subscriptions: also on subscription metadata, which Stripe copies onto invoices); a code never overrides a referral reference, and unknown codes are recorded for review without crediting. - Pin the delivery endpoint to Stripe API version 2024-06-20 and select exactly the purchase events below plus the informational events listed after them. For a subscription checkout, qualification and invoice revenue are distinct: the checkout and invoice must not each create the same commission.
- Confirm your application’s return URL resumes the correct customer context. Returning to a success page alone is not proof of a paid invoice.
| Event path | Expected purpose |
|---|---|
checkout.session.completed | Associate and qualify the referral; post one-time payment revenue only when applicable. |
checkout.session.async_payment_succeeded | The same association for a delayed payment method that settles after checkout. |
invoice.paid | Accrue eligible subscription invoice revenue against the qualified referral. |
charge.refunded | Reference the original purchase and append the matching commission adjustment. |
The canonical adapter supports Stripe event version 2024-06-20. Known non-earning events are additionally accepted as informational records: invoice.payment_failed, invoice.voided, invoice.marked_uncollectible, invoice.created, invoice.finalized, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, checkout.session.expired. Other versions and unsupported payment shapes are recorded for review; they do not silently become earnings.
For new programs, Checkout revenue is the collected total after discounts, less explicit total_details.amount_tax and total_details.amount_shipping. Invoice revenue requires paid status, a payment intent, a full payment matching the invoice total, and status_transitions.paid_at; tax and shipping are excluded. Partial or multi-payment invoice shapes need a supported adapter. Product subsets require item allocation; prose in program eligibility does not configure exclusions.
Refund delivery is cumulative at the charge level. A mixed eligible/ineligible refund without an explicit allocation is held for review; no guessed split changes earnings. Existing qualified referrals retain their saved calculation.
Run an isolated installation test
- Save your program and select Stripe in its Tracking step. In Store settings choose Isolated setup tests and save the signing secret from your Stripe sandbox endpoint. The test key must differ from your live key.
- Use
/api/ingest-test/<tenant-id>/stripefor the sandbox endpoint. Create an isolated test in the Tracking step or tracking console; this returns the exact test referral reference, currency, purchase amount and expected commission. The fixture is a 10,000 minor-unit purchase carrying 500 tax and 500 shipping, leaving 9,000 eligible revenue for a new program. - Carry that reference in Checkout
client_reference_id. For subscriptions, also set subscription metadataphilos_ref. Use a fictional customer and the exact purchase amount displayed in the receipt. - Deliver
checkout.session.completedwithlivemode: falseand paid status. A one-time payment can complete the diagnostic calculation. A subscription checkout only matches the referral; a paid invoice from the same customer and subscription must follow before the test passes. - Refresh the receipt. Compare expected and calculated minor-unit amounts. Repeating the identical provider event returns its original result. An invoice delivered before checkout stays retryable.
Tests expire after 24 hours. Changed economics, destination, provider or signing keys require current evidence. Setup navigation does not invalidate the test. These records cannot credit real earnings, send notifications or move money.
Eligibility, real referral capture, renewals, refund reconciliation and provider payout failures still need separate end-to-end release checks in an authorized test environment. A diagnostic purchase receipt does not claim those checks passed.
Resolve a failure
Nothing arrived
Check the exact workspace endpoint, Stripe delivery history, mode, and enabled events. A successful local checkout can still have failed event delivery. Retry the original event only after fixing the configuration.
The signature was rejected
Verify the endpoint’s signing secret and preserve the raw request body. A secret from another endpoint or mode will not authenticate this delivery.
The event arrived but was unattributed
Check that the referral reference survived checkout and that the customer maps to the qualified referral. Verify partner eligibility and accepted terms. Do not create a second purchase just to retry attribution.
The amount is unexpected
Compare the original amount, currency, accepted reward terms, earning window, and refund history. Preserve the source record while investigating; do not rewrite settled earnings.
The partner is not ready
Review approval, required identity evidence, accepted terms, and any restrictions. An invitation or an email address by itself does not satisfy every eligibility condition.
Go live deliberately
Stripe publication waits for a signed live delivery. A passed sandbox test does not unlock a Stripe program, and neither does adding a live signing secret or entering account ids. Philos cannot send that delivery for you: the first signed informational event your live endpoint sends during ordinary activity — for example a new invoice or a subscription update — records the live account and endpoint. Rotating the live signing secret requires a new delivery.
Verify live delivery configuration separately from a passed test. Review the live offer, payment policy, subscription eligibility, and launch URL. Record the first real event outcome and keep diagnostics visible.
Never infer successful bank delivery from a conversion receipt. Partner payment setup and authorization follow their own process.