Payment API

https://ingest.traceten.com/v1/server/payments

{ "status": "recorded", "transaction_id": "pay_9fK2mQ" }

{
  "site_id": "ttid_7Rb4TrC1dTbnD8w3s1TS12",
  "transaction_id": "pay_9fK2mQ",
  "amount": 49.99,
  "currency": "USD",
  "refunded": true
}

{
  "site_id": "ttid_7Rb4TrC1dTbnD8w3s1TS12",
  "transaction_id": "pay_9fK2mQ",
  "amount": 49.99,
  "currency": "USD",
  "refunded": true,
  "refunded_amount": 12.5
}

{
  "site_id": "ttid_7Rb4TrC1dTbnD8w3s1TS12",
  "transaction_id": "pay_9fK2mQ",
  "amount": 49.99,
  "currency": "USD",
  "refunded": true,
  "refunded_amount": 22.5
}

{
  "site_id": "ttid_7Rb4TrC1dTbnD8w3s1TS12",
  "transaction_id": "sub_trial_8812",
  "amount": 0,
  "currency": "USD",
  "provider": "polar",
  "email": "ada@example.com"
}

const ZERO_DECIMAL = new Set(["ISK", "JPY", "KRW"]);
const toMajor = (minor: number, currency: string): number =>
  ZERO_DECIMAL.has(currency.toUpperCase()) ? minor : minor / 100;

ZERO_DECIMAL = {"ISK", "JPY", "KRW"}

def to_major(minor: int, currency: str) -> float:
    return minor if currency.upper() in ZERO_DECIMAL else minor / 100

curl -X POST https://ingest.traceten.com/v1/server/payments \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "ttid_7Rb4TrC1dTbnD8w3s1TS12",
    "transaction_id": "pay_9fK2mQ",
    "amount": 49.99,
    "currency": "USD",
    "provider": "dodo",
    "email": "ada@example.com"
  }'

{ "status": "recorded", "transaction_id": "pay_9fK2mQ" }

import { Client } from "@traceten/sdk-node";
import DodoPayments from "dodopayments";

const traceten = new Client({
  siteId: "ttid_7Rb4TrC1dTbnD8w3s1TS12",
  host: "https://ingest.traceten.com",
  apiKey: process.env.TRACETEN_API_KEY!,
});

const dodopayments = new DodoPayments({ bearerToken: process.env.DODO_API_KEY! });

// Dodo reports minor units. Most currencies have two decimal places, but JPY,
// KRW and ISK have none: 5000 there means 5000 yen, not 50.
const ZERO_DECIMAL = new Set(["ISK", "JPY", "KRW"]);
const toMajor = (minor: number, currency: string): number =>
  ZERO_DECIMAL.has(currency.toUpperCase()) ? minor : minor / 100;

app.post("/webhooks/dodo", async (req, res) => {
  if (req.body.type === "payment.succeeded") {
    const payment = req.body.data;
    await traceten.payment({
      transactionId: payment.payment_id,
      amount: toMajor(payment.total_amount, payment.currency),
      currency: payment.currency,
      provider: "dodo",
      visitorId: payment.metadata?.traceten_visitor_id,
      email: payment.customer.email,
      customerId: payment.customer.customer_id,
      // Dodo always settles to USD, GBP or EUR (all priced by Traceten),
      // so this is a safe fallback for the rare native currency
      // Traceten can't price on its own. Omit either field and the SDK sends
      // neither; only pass both when Dodo's payload includes them.
      ...(payment.settlement_amount !== undefined && payment.settlement_currency
        ? {
            settlementAmount: toMajor(payment.settlement_amount, payment.settlement_currency),
            settlementCurrency: payment.settlement_currency,
          }
        : {}),
    });
  }

  if (req.body.type === "refund.succeeded") {
    const refund = req.body.data;

    // `refunded_amount` is the TOTAL refunded against the payment so far, and
    // the webhook only states THIS refund's amount. Read the payment back and
    // sum every refund on it.
    const payment = await dodopayments.payments.retrieve(refund.payment_id);
    const currency = payment.currency;
    const refundedMinor = (payment.refunds ?? []).reduce((sum, r) => sum + r.amount, 0);
    const isFullRefund = refundedMinor >= payment.total_amount;

    await fetch("https://ingest.traceten.com/v1/server/payments", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.TRACETEN_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        site_id: "ttid_7Rb4TrC1dTbnD8w3s1TS12",
        // The ORIGINAL payment's id, so the refund lands against it.
        transaction_id: refund.payment_id,
        amount: toMajor(payment.total_amount, currency),
        currency,
        provider: "dodo",
        refunded: true,
        // Left off on a full refund: that takes back everything outstanding,
        // which lands on exactly zero even if the summed refunds are a cent short.
        ...(isFullRefund ? {} : { refunded_amount: toMajor(refundedMinor, currency) }),
      }),
    });
  }

  res.sendStatus(200);
});

import os
import traceten

client = traceten.Client(
    "ttid_7Rb4TrC1dTbnD8w3s1TS12",
    "https://ingest.traceten.com",
    api_key=os.environ["TRACETEN_API_KEY"],
)

@app.post("/webhooks/polar")
def polar_webhook(event: dict):
    order = event["data"]
    client.payment(
        transaction_id=order["id"],
        # `to_major` from the note above: Polar sends minor units.
        amount=to_major(order["amount"], order["currency"]),
        currency=order["currency"],
        provider="polar",
        email=order["customer"]["email"],
        renewal=order["billing_reason"] == "subscription_cycle",
    )
    return {"ok": True}

app.post("/webhooks/lemonsqueezy", async (req, res) => {
  const order = req.body.data.attributes;
  await traceten.payment({
    transactionId: req.body.data.id,
    // Lemon Squeezy sends minor units in `total`; `total_formatted` is a
    // display string. `toMajor` is from the note above.
    amount: toMajor(order.total, order.currency),
    currency: order.currency,
    provider: "lemonsqueezy",
    email: order.user_email,
    refunded: order.refunded,
  });
  res.sendStatus(200);
});

app.post("/webhooks/paddle", async (req, res) => {
  const txn = req.body.data;
  await traceten.payment({
    transactionId: txn.id,
    // Paddle sends minor units as a STRING. `toMajor` is from the note above.
    amount: toMajor(Number(txn.details.totals.grand_total), txn.currency_code),
    currency: txn.currency_code,
    provider: "paddle",
    email: txn.customer?.email,
    customerId: txn.customer_id,
  });
  res.sendStatus(200);
});

await traceten.payment({
  transactionId: order.id,
  amount: order.total,
  currency: "USD",
  provider: "kajabi",
  visitorId: visitorIdFromClient,
});

// Client-side: read the visitor id and send it to your own backend
const visitorId = window.traceten.getVisitorId(); // null before the first pageview resolves