Settle usage from provider evidence without overstating its meaning

Identify which fact the callback establishes

A provider event can establish an accepted request, a changed resource state or a reported cost. Those are different facts. A usage record marked provider_confirmed describes supported cost evidence; it does not automatically prove a recipient read a message or a human answered a call.

Lupin’s usage ledger labels configured rates as configured_estimate. Its documentation describes signed Telnyx message.finalized events replacing supported SMS estimates with a provider-reported USD amount. Keep that narrow provenance visible rather than labeling every settled action as a final invoice charge.

Verify authenticity before interpreting money

The documented Telnyx signature covers exact timestamp and raw-body bytes and is subject to a five-minute window. Missing or unavailable verification fails closed before processing. Parsing a plausible cost field from an unsigned request would let an attacker alter the ledger without controlling the provider.

Preserve the unmodified payload until signature verification completes and use the correct account verification key. Do not reserialize parsed JSON and then verify that new string. Credential access and callback verification should stay server-side; ordinary agent context does not need the signing material or complete callback body.

Match the original accounting identity

Associate the callback with the correct organization and saved provider reference. Do not select an arbitrary recent message that looks similar. A durable provider reference lets the settlement update the original usage event rather than insert another charge each time the callback is delivered.

Callbacks can arrive after local recovery or in a different order than client responses. Preserve newer state and avoid allowing an old projection to erase later evidence. The operation journal, local resource and usage ledger have different responsibilities, so check their references rather than assuming their update timestamps must be identical.

Reject unsupported monetary interpretations

Lupin accepts supported USD amounts at its integer microdollar precision. Other currencies, absent amounts and unsupported precision remain unpriced; no exchange rate or missing fee is invented. An empty amount is not evidence of free usage. A configured maximum remains an estimate until supported provider evidence replaces it.

SMS estimates require a maximum for the entire accepted send, including segment, media, carrier and destination effects. A per-segment quote alone cannot be substituted for that documented rate basis. Provider-confirmed cost also remains distinct from subscription invoices, recurring charges and the customer’s retail overage calculation.

Reconcile without duplicate settlement

Use local callback fixtures for repeated delivery, missing amount, unsupported currency, too much precision and an unknown provider reference. Verify that the original record changes only under the intended evidence and that replay does not add a second usage quantity. These tests require no live message or phone number.

In an incident, show the earlier estimate, the confirmed amount when present, the evidence source and remaining excluded costs. If a callback cannot be authenticated or matched, leave it unresolved rather than manually forcing the ledger to a convenient number. A smaller honest uncertainty is more useful than a false final total.

Sources & verification

Reviewed against the checked-in Lupin implementation and official reference documentation on 2026-11-05. Operational examples are illustrative; no live paid action, provider mutation or external message was executed.

• Lupin usage ledger and spending limits ↗Checked 2026-11-05
• Lupin phone operations ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.