Manual Payment API
Send custom payment events to Talivia from your backend.
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.
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:
sessionIdproviderCustomerIdexternalCustomerIdemailemailHash
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:
| Field | Type | Meaning |
|---|---|---|
providerSubscriptionId | string | The stable subscription ID in your billing system. |
isRenewal | boolean | false for the first payment, true for a renewal. Send a JSON boolean. |
occurredAt | ISO date string | When 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.
{
"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
- Send a test payment from your backend.
- Open Talivia payments for the website.
- Confirm the amount, currency, provider name, and transaction id.
- Open the visitor profile and verify that the spend appears in the matched visitor journey.