// e-commerce and billing
Via APIStripe email verification with pingutil
Stripe takes the email the customer enters, and if it is mistyped or a throwaway, receipts, failed-payment notices and renewal reminders go nowhere. Listening for customer.created or checkout.session.completed and writing the pingutil result to customer metadata gives your billing and fraud logic a clear signal, without touching the payment itself.
Where it connects: Stripe webhooks (customer.created, checkout.session.completed) plus customer metadata via the Customers API
What goes wrong without it
- Failed-payment emails go to an address with a typo, so the card never gets updated and the subscription churns.
- People start a new trial every month with a different temp-mail address and the same card.
- Fake accounts that sign up with throwaway inboxes are the ones that end up disputing charges.
What you can do with Stripe and pingutil
Store a verification result on the customer
Write pingutil_status and pingutil_reason into customer metadata. Metadata is visible in the Dashboard and in every API response, so support and your app can both read it.
Stop repeat trials from throwaway inboxes
When category is disposable or verdict.is_spam is true, have your app skip the trial or require a payment method upfront for that account.
Fix typos before dunning starts
If did_you_mean is set, prompt the user in your app to confirm their billing email, so failed-payment emails reach them.
Set it up
- 1
Create an API key in the pingutil dashboard and store it as PINGUTIL_KEY.
- 2
Add a webhook endpoint in the Stripe Dashboard (or with the Stripe CLI) listening for customer.created and, for Checkout, checkout.session.completed.
- 3
Verify the Stripe-Signature header with stripe.webhooks.constructEvent using the raw request body.
- 4
Return 200 quickly, then verify the email with pingutil.
- 5
Write the result to the customer with stripe.customers.update and metadata, and read it from your app when granting trials or credits.
import express from 'express';
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
let event;
try {
event = stripe.webhooks.constructEvent(req.body, req.get('stripe-signature'), process.env.STRIPE_WEBHOOK_SECRET);
} catch {
return res.sendStatus(400);
}
res.sendStatus(200);
if (event.type === 'customer.created' && event.data.object.email) {
const customer = event.data.object;
verifyAndTag(customer.id, customer.email).catch(console.error);
}
});
async function verifyAndTag(customerId, 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; // 429 quota_exceeded or outage: leave metadata unset
result = await res.json();
} catch {
return;
}
await stripe.customers.update(customerId, {
metadata: {
pingutil_status: result.status,
pingutil_reason: result.reason,
pingutil_disposable: String(result.checks.disposable),
pingutil_did_you_mean: result.did_you_mean || '',
},
});
}
app.listen(3000);What to do with each result
| pingutil result | Action in Stripe |
|---|---|
| status: "valid" | Store metadata, nothing else. |
| status: "invalid" | Ask the user to update their billing email in your app before the first invoice or renewal. |
| checks.disposable: true | Skip the free trial or require a card upfront for this customer in your app logic. |
| did_you_mean is set | Show a "did you mean" prompt in your billing settings page. |
| status: "risky" or "unknown" | Store only. Do not cancel or refund on these results. |
Limits to plan for
- Stripe expects a quick 2xx from webhook endpoints and retries otherwise, so verify after responding.
- A Checkout session for a guest may have no Customer object. In that case read customer_details.email from the session and store the result in your own database.
- pingutil does not see card or payment data and is not a payment fraud score. Use it as one signal next to Stripe Radar.
Stripe documentation
Stripe is a trademark of its owner. This integration uses Stripe's documented extension points; it is not an official Stripe app.
Common questions
- Should I verify on customer.created or checkout.session.completed?
- customer.created if you create customers from your app at sign-up, which is earliest. checkout.session.completed if Stripe Checkout creates the customer, since that is when you first see the address.
- Can pingutil check emails before Stripe Checkout opens?
- Yes, if you collect the email in your own form first. Call your backend, which calls pingutil, then pass the email to the Checkout session.
- Is there a pingutil Stripe app?
- No. You connect it through your own webhook endpoint as shown.
Stop bad addresses in Stripe 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 Stripe setup will receive.