Payments
Virling reads payments from your provider with a read-only key and matches them to visits. It never creates, changes or refunds anything.
Supported providers
Which key to create
| Provider | Key | Access |
|---|---|---|
| Stripe | Restricted key, rk_live_ or rk_test_ | Read on Charges, Checkout Sessions, Customers, Events, Invoices, Subscriptions and PaymentIntents |
| Dodo Payments | API key, live or test mode | Reads payments, refunds and subscriptions |
| Polar | Organization access token, polar_oat_ | orders:read and refunds:read |
| LemonSqueezy | API key | Full access to every store on the account. LemonSqueezy keys cannot be limited. |
Before saving, Virling makes one test request with the key. If the key is wrong or lacks access, the app shows the provider’s error and the key is not stored.
Connect a provider
- In the app, open your site, then Setup, then Connect payments. The address is
/app/yourdomain.com/setup/payments. - Pick the provider and paste the key.
- Click Connect and backfill.
You can connect more than one provider to the same site. Each site has at most one connection per provider.
What Virling reads
- Backfill. The first sync imports the last 90 days of payments.
- Polling. After that, every connected provider is polled once a minute. There are no webhooks, so nothing has to reach your server from the provider.
- Per payment it keeps the provider’s payment ID, time, amount and currency, the refunded amount, the status, the customer ID, whether it is a renewal, and the visitor ID if checkout carried one.
- Refunds and disputes update the payment’s refunded amount, so revenue is shown after refunds.
- Currency. Amounts are converted to USD for reports. See Currencies.
Webhooks for any provider are Not available yet. New payments appear within about a minute of the next poll.
How keys are stored
Keys are encrypted with AES-256-GCM before they are written to virling.sqlite. The encryption key is secret.key in the data folder, or VIRLING_SECRET_KEY if you set it. The app only ever shows the last characters of a key.
Warning
Keep the secret key with the data. If
secret.keyis lost, orVIRLING_SECRET_KEYchanges, stored provider keys can no longer be decrypted, sync fails with “decryption failed, wrong secret key?”, and every provider has to be reconnected.
Replace or disconnect a key
On the same Connect payments screen, or in site settings at /app/yourdomain.com/settings:
- Replace key saves a new key and restarts the sync from the 90-day backfill. Payments already imported are updated in place, not duplicated.
- Disconnect deletes the stored key and stops syncing right away. Payments already imported stay in your reports.
To revoke Virling’s access completely, also delete or roll the key in your provider’s dashboard.
Sync errors
The last sync time and the last error for each provider show in site settings. A failing provider keeps being retried every minute, and the other providers keep syncing.
Next: link checkout to visits, so new payments can be attributed.