Built for integration boundaries

A small API surface for decisions that must stay correct.

Validate referral codes where customers use them. Record commercial outcomes and refunds from trusted server code. Keep every retry tied to a stable external identity.

Server-side quick start

Send the paid outcome once your provider confirms it.

Use an environment-bound secret key, a stable transaction ID and an idempotency key derived from the immutable event—not request time or a random retry.

  • Test keys select sandbox environments.
  • Secret keys stay in trusted server code.
  • Exact retries return the canonical result.
  • Changed requests conflict instead of rewriting money.
conversion.tsNode.js
import { ReferralRails } from '@referralrails/sdk-node';

const ref = new ReferralRails({
  apiKey: process.env.REFERRALRAILS_SECRET_KEY,
});

await ref.conversions.record({
  appUserId: customer.id,
  externalProductId: product.id,
  externalTransactionId: order.id,
  grossMinor: 4900,
  currency: 'USD',
  kind: 'ONE_OFF',
  occurredAt: new Date(),
}, {
  idempotencyKey: 'order:' + order.id,
});

Integration model

Keep each credential at its real trust boundary.

01

Public validation

Browser-safe publishable keys can validate codes and support narrow attribution flows without management authority.

02

Server recording

Secret keys create users and paid outcomes from the system that already owns provider confirmation.

03

Signed delivery

Webhook consumers verify the exact raw body and timestamp before parsing or acting on a delivery.