Talivia Docs
Talivia Docs
HomeDashboard
IntroductionInstallationTeamGetting updates
Self-hostingInstall TaliviaUpdatingCustom domainOwner accountLicense and transfersCloudflare and backupsUninstallTroubleshooting
Stripe
Yolfi
Dodo Payments
LemonSqueezy
Polar
Manual Payment APITesting payment integrations
Integrations
AI agents and MCPllms.txtllms-full.txt
Revenue

Manual Payment API

Send custom payment events to Talivia from your backend.

View Markdown

Use the Manual Payment API when revenue comes from a custom checkout, bank transfer, crypto processor, app store, invoice system, or another provider that Talivia does not connect to directly.

Create an API key

Open Website settings -> API keys and generate a key. Talivia creates it for the current website.

Copy the secret immediately because it is shown only once. Store it only on your backend and do not expose it in browser code.

Send a payment

Send payment events to Talivia after your backend confirms the money was received.

Before checkout, send window.talivia.getSessionId() to your backend and keep it with the order as sessionId.

Record a confirmed payment
await fetch('https://talivia.com/api/payments/manual', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-talivia-api-key': process.env.TALIVIA_API_KEY,
  },
  body: JSON.stringify({
    websiteId: 'YOUR_WEBSITE_ID',
    transactionId: 'order_123',
    amount: 49,
    currency: 'USD',
    providerName: 'manual',
    providerPaymentId: 'payment_123',
    providerCustomerId: 'customer_123',
    sessionId: order.sessionId,
  }),
});

Use stable ids. transactionId should be unique for the payment in your system. Reuse the same id if you retry the request.

Supported attribution fields

Send the session field when possible:

  • sessionId
  • providerCustomerId
  • externalCustomerId
  • email
  • emailHash

Talivia uses sessionId to connect the payment to the exact visitor journey. Customer fields can reconnect later renewals after the initial payment has been matched.

Subscription payments and renewals

Use these optional fields for subscription payments:

FieldTypeMeaning
providerSubscriptionIdstringThe stable subscription ID in your billing system.
isRenewalbooleanfalse for the first payment, true for a renewal. Send a JSON boolean.
occurredAtISO date stringWhen the payment was received. Defaults to the request time.

Send a new transactionId for each charge and reuse it only when retrying that same charge. Keep providerName, providerSubscriptionId, and providerCustomerId stable across renewals. A renewal does not need a new browser visit or sessionId.

Annual subscription renewal
{
  "websiteId": "YOUR_WEBSITE_ID",
  "transactionId": "annual_charge_2026",
  "providerName": "custom_billing",
  "providerSubscriptionId": "subscription_123",
  "providerCustomerId": "customer_123",
  "amount": 360,
  "currency": "USD",
  "isRenewal": true,
  "occurredAt": "2026-10-19T10:00:00Z"
}

This records the full $360 on the payment date. Revenue is not spread over the subscription months. If isRenewal is omitted, Talivia looks for an earlier payment with the same provider and subscription ID. Send the flag explicitly when the first payment predates your Talivia history.

Verify

  1. Send a test payment from your backend.
  2. Open Talivia payments for the website.
  3. Confirm the amount, currency, provider name, and transaction id.
  4. Open the visitor profile and verify that the spend appears in the matched visitor journey.

Test and troubleshoot Polar

Verify the Polar connection, webhook, attribution, subscriptions, and refunds.

Testing payment integrations

Keep sandbox and production revenue separate, then follow the checks for your payment provider.