// e-commerce and billing
Via APIChargebee email verification with pingutil
Chargebee sends invoices, dunning and renewal notices to the customer email, and a mistyped or throwaway address quietly turns a recoverable failed payment into churn. A webhook handler on customer_created verifies the address with pingutil and saves the result in the customer meta_data, so your app and finance team know which accounts can actually be reached.
Where it connects: Chargebee webhooks (customer_created event) plus customer meta_data via the Update a customer API
What goes wrong without it
- Dunning emails for a failed card go to a typo, so the customer never updates the card and we lose the subscription.
- The same people keep signing up for trials with throwaway addresses and our trial-to-paid numbers look worse than they are.
- Finance chases unpaid invoices for accounts whose billing email never existed.
What you can do with Chargebee and pingutil
Record verification on the customer
Write pingutil_status and reason into meta_data with the Update a customer API, so it shows up in the customer record and in later API calls.
Catch trial abuse early
Disposable or randomized addresses come back with checks.disposable or status risky with reason randomized_local_part. Your app can shorten or skip the trial for those.
Fix billing emails before dunning
When the status is invalid or did_you_mean is set, ask the customer to update their billing email in your app before the first renewal.
Set it up
- 1
Create an API key in the pingutil dashboard and a Chargebee API key with write access to customers.
- 2
In Chargebee, add a webhook endpoint with basic authentication credentials and subscribe it to customer_created.
- 3
In the handler, check the basic auth credentials, respond 200, then read content.customer.email.
- 4
Call pingutil /v1/verify with a timeout and catch errors.
- 5
Write the result to the customer meta_data using the Chargebee Node SDK customer.update call.
import express from 'express';
import Chargebee from 'chargebee';
const chargebee = new Chargebee({ site: process.env.CHARGEBEE_SITE, apiKey: process.env.CHARGEBEE_API_KEY });
const app = express();
const expectedAuth = 'Basic ' + Buffer.from(process.env.CB_HOOK_USER + ':' + process.env.CB_HOOK_PASS).toString('base64');
app.post('/webhooks/chargebee', express.json(), (req, res) => {
if (req.get('authorization') !== expectedAuth) return res.sendStatus(401);
res.sendStatus(200);
const event = req.body;
if (event.event_type === 'customer_created' && event.content.customer.email) {
const customer = event.content.customer;
verifyCustomer(customer.id, customer.email).catch(console.error);
}
});
async function verifyCustomer(id, email) {
let result;
try {
const res = await fetch('https://pingutil.com/v1/verify', {
method: 'POST',
headers: { authorization: 'Bearer ' + process.env.PINGUTIL_KEY, 'content-type': 'application/json' },
body: JSON.stringify({ email }),
signal: AbortSignal.timeout(30000),
});
if (!res.ok) return; // fail open
result = await res.json();
} catch {
return;
}
await chargebee.customer.update(id, {
meta_data: {
pingutil_status: result.status,
pingutil_reason: result.reason,
pingutil_did_you_mean: result.did_you_mean,
},
});
}
app.listen(3000);What to do with each result
| pingutil result | Action in Chargebee |
|---|---|
| status: "invalid" | Prompt for a new billing email in your app and tell finance not to rely on email for this invoice. |
| did_you_mean is set | Show the suggestion in your billing settings so the customer can correct it. |
| checks.disposable: true | Skip or shorten the trial in your app. Review manually before using Chargebee fraud_flag. |
| status: "risky" or "unknown" | Store in meta_data only. Do not cancel subscriptions on these results. |
Limits to plan for
- Chargebee webhooks support basic authentication only, not signed payloads, so use long random credentials and HTTPS.
- Chargebee retries failed webhooks and can deliver them late or out of order. Updating meta_data is idempotent, so retries are harmless.
- Webhook payloads are point-in-time snapshots, so fetch the customer from the API if you need its current email before verifying a delayed event.
Chargebee documentation
- www.chargebee.com/docs/billing/2.0/site-configuration/events_and_webhooks
- apidocs.chargebee.com/docs/api/events
- apidocs.chargebee.com/docs/api/customers/update-a-customer
Chargebee is a trademark of its owner. This integration uses Chargebee's documented extension points; it is not an official Chargebee app.
Common questions
- Can I verify before the Chargebee customer is created?
- Yes, if your app creates customers through the API. Call pingutil from your sign-up endpoint first, then create the customer with the result already in meta_data.
- Should I mark disposable customers as fraudulent?
- We do not recommend doing it automatically. A throwaway inbox is a strong trial-abuse signal but not proof of payment fraud, so route those to a person.
Stop bad addresses in Chargebee today
Sign in with your email, create an API key and paste it into the step above. Test on a few real addresses first: the live demo shows exactly what your Chargebee setup will receive.