Skip to content

// e-commerce and billing

Via API

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

    Create an API key in the pingutil dashboard and a Chargebee API key with write access to customers.

  2. 2

    In Chargebee, add a webhook endpoint with basic authentication credentials and subscribe it to customer_created.

  3. 3

    In the handler, check the basic auth credentials, respond 200, then read content.customer.email.

  4. 4

    Call pingutil /v1/verify with a timeout and catch errors.

  5. 5

    Write the result to the customer meta_data using the Chargebee Node SDK customer.update call.

Webhook handler for customer_created
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 resultAction 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 setShow the suggestion in your billing settings so the customer can correct it.
checks.disposable: trueSkip 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

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.