Skip to content

// e-commerce and billing

Via API

Stripe 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. 1

    Create an API key in the pingutil dashboard and store it as PINGUTIL_KEY.

  2. 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. 3

    Verify the Stripe-Signature header with stripe.webhooks.constructEvent using the raw request body.

  4. 4

    Return 200 quickly, then verify the email with pingutil.

  5. 5

    Write the result to the customer with stripe.customers.update and metadata, and read it from your app when granting trials or credits.

Express webhook for customer.created
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 resultAction 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: trueSkip the free trial or require a card upfront for this customer in your app logic.
did_you_mean is setShow 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.