HALPIITax ID

Stripe validates the format of Latin American tax IDs, not the registry: how to close the gap

Last reviewed 2026-11-15 · HALPII S.A.C.

Stripe checks the format of a Peruvian RUC, a Colombian NIT, a Mexican RFC or a Chilean RUT when you save it on a customer. It does not ask the tax authority whether the number belongs to a registered, active business. Stripe says so in its own documentation. This guide shows where that line sits for each Latin American ID type and how to add a registry check next to Stripe with a few lines of Node or Python.

What Stripe says it validates

From Stripe's customer tax ID documentation:

  • "Stripe only checks the format of tax ID types other than AU ABN, EU VAT, and GB VAT, and doesn't validate them against government databases."
  • "For all other tax ID types, Stripe only checks the format. A format check doesn't confirm that the tax ID exists in a government database."
  • "The invoice includes the customer tax ID whether or not it's valid."
  • Even for the three types it checks against a registry: "we don't continue to validate them over time."

So every Latin American type in Stripe's list (pe_ruc, co_nit, mx_rfc, cl_tin, cr_tin, do_rcn and the rest) gets a format check only. That is a reasonable default for a global payments company. It also means the registry check is your job.

Country by country

CountryStripe typeWhat Stripe checksChanges Stripe Tax?*What HALPII Tax ID checks
Perupe_ruc
Peruvian RUC number
Format onlyYesOfficial registry
Legal name, status, HABIDO condition, fiscal address · daily copy
Colombiaco_nit
Colombian NIT number
Format onlyNoOfficial registry
Legal name, commercial registration status, last renewal · live
Mexicomx_rfc
Mexican RFC number
Format onlyNoFormat + tax-authority lists
Format, check digit, SAT list status (never "active") · periodic copy
Chilecl_tin
Chilean TIN
Format onlyYesOfficial registry
Legal name and status · periodic copy
Costa Ricacr_tin
Costa Rican tax ID
Format onlyNoOfficial registry
Hacienda status, tax regime, moroso / omiso, activities · live (beta)
Dominican Republicdo_rcn
Dominican RCN number
Format onlyNoOfficial registry
Legal name and status (RNC); format check for other ID types · daily copy
Argentinaar_cuit
Argentinian tax ID number
Format onlyNoFormat only
Structure and check digit, offline
Brazilbr_cnpj
Brazilian CNPJ number
Format onlyNoFormat only
Structure and check digit, offline
Ecuadorec_ruc
Ecuadorian RUC number
Format onlyNoFormat only
Structure and check digit, offline
Uruguayuy_ruc
Uruguayan RUC number
Format onlyYesFormat only
Structure and check digit, offline
Paraguaypy_ruc
Paraguayan RUC number
Format onlyNoFormat only
Structure and check digit, offline
Boliviabo_tin
Bolivian tax ID
Format onlyNoFormat only
Structure and check digit, offline
Venezuelave_rif
Venezuelan RIF number
Format onlyNoFormat only
Structure and check digit, offline

Stripe columns: Stripe's Supported Tax ID types and Validation sections, read on 2026-11-15. *Stripe's column "Impact in Tax Calculation", which its footnote explains as: "Stripe Tax won't apply tax if this tax ID is provided, in line with the relevant laws." HALPII columns: generated from the same catalogue as GET /v1/countries. Stripe also lists El Salvador (sv_nit), which this API does not cover yet.

Where a registry exists and we read it (Peru, Colombia, Chile, Costa Rica, Dominican Republic), the answer says whether the business is registered and active, with its legal name. Mexico publishes no RFC registry, so for an RFC we check the format and the SAT's public lists of taxpayers (art. 69-B and art. 69); the verdict is never pass. For Argentina, Brazil, Ecuador, Uruguay, Paraguay, Bolivia, Venezuela, we check the structure and check digit, which is what Stripe already does. The answer says verification_level: "format" so nobody mistakes it for a registry check.

Why the gap matters

  • Invoices to businesses that are gone. A RUC can be well formed and belong to a company that SUNAT deregistered years ago. The format check passes, Stripe prints the number on the invoice, and your customer's accounts-payable team rejects it, or their tax adviser does at year end. Peru's rules on buying from a NO HABIDO taxpayer are one example of how a registry flag reaches the buyer.
  • Tax treatment. For pe_ruc, cl_tin and uy_ruc, Stripe's table marks "Impact in Tax Calculation" as Yes, and its docs add that Stripe Tax applies the reverse charge or zero rate "when the tax ID has the required number format, regardless of the government verification result." A made-up number in the right shape can change what you charge.
  • KYB and accounts payable. If you onboard business customers or pay sellers in Latin America, the tax ID is often the only official identifier you collect. Checking it against the registry at signup, and again before large invoices, catches typos, shell entities and companies that stopped trading.

How to close it

Two hooks cover most integrations:

  1. When the tax ID is saved. Listen for customer.tax_id.created ("Occurs whenever a tax ID is created for a customer"). Its data.object is a Tax ID object with type, value, country and customer. Call our API and store the verdict in the customer's metadata.
  2. Before you invoice. Read the stored verdict before you create a one-off invoice, and re-check if it is missing, stale or unchecked. For subscriptions, Stripe waits an hour after a successful response to invoice.created before attempting payment, which leaves room to hold a draft invoice for review.

Stripe asks webhook endpoints to verify the signature with the raw request body and to "quickly return a successful status code (2xx) before any complex logic" (Stripe webhooks guide). Both samples do that. The registry call happens after the 200, or on your job queue.

Node.js (Express)

// npm install stripe express
import express from 'express';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const HALPII = 'https://taxid.halpii.com';

// Peru, Mexico, Colombia and Costa Rica have their own routes; the rest go through /v1/validate.
const ROUTES = { pe_ruc: 'pe/ruc', mx_rfc: 'mx/rfc', co_nit: 'co/nit', cr_tin: 'cr/cedula' };
const COUNTRY = {
  cl_tin: 'CL',
  do_rcn: 'DO',
  ar_cuit: 'AR',
  br_cnpj: 'BR',
  ec_ruc: 'EC',
  uy_ruc: 'UY',
  py_ruc: 'PY',
  bo_tin: 'BO',
  ve_rif: 'VE',
};

async function checkTaxId(type, value) {
  const id = encodeURIComponent(value);
  let url;
  if (ROUTES[type]) url = `${HALPII}/v1/${ROUTES[type]}/${id}`;
  else if (COUNTRY[type]) url = `${HALPII}/v1/validate?country=${COUNTRY[type]}&id=${id}`;
  else return null; // not a Latin American type: leave it to Stripe

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.HALPII_TAXID_KEY}` },
    signal: AbortSignal.timeout(15_000),
  });
  // 503: the registry did not answer (not billed). 429: daily allowance used. Try again later.
  if (res.status === 503 || res.status === 429) return { verdict: 'unchecked', reason: `HTTP ${res.status}` };
  const body = await res.json();
  if (res.status === 400) return { verdict: 'fail', reason: body.error, level: body.verification_level };
  if (!res.ok) throw new Error(`HALPII Tax ID ${res.status}: ${body.error}`);
  return {
    verdict: body.assessment.verdict, // pass | review | fail
    reason: body.assessment.reasons.join(' '),
    level: body.verification_level, // official_registry | format_and_lists | format
    asOf: body.source?.data_as_of ?? '',
  };
}

async function recordVerdict(customerId, taxId) {
  const r = await checkTaxId(taxId.type, taxId.value);
  if (!r) return null;
  await stripe.customers.update(customerId, {
    metadata: {
      taxid_verdict: r.verdict,
      taxid_level: r.level ?? '',
      taxid_value: taxId.value,
      taxid_checked_at: new Date().toISOString(),
      taxid_reason: r.reason.slice(0, 500), // metadata values: 500 characters max
    },
  });
  return r;
}

const app = express();

// Stripe needs the raw body to verify the signature.
app.post('/stripe/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = stripe.webhooks.constructEvent(req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET);
  } catch (err) {
    return res.status(400).send(`Webhook error: ${err.message}`);
  }
  res.sendStatus(200); // answer Stripe first, then do the slow part
  if (event.type === 'customer.tax_id.created' && event.data.object.customer) {
    recordVerdict(event.data.object.customer, event.data.object).catch(console.error);
  }
});

// Before you create a one-off invoice: re-check anything not yet checked, then decide.
async function canInvoice(customerId) {
  const customer = await stripe.customers.retrieve(customerId, { expand: ['tax_ids'] });
  let verdict = customer.metadata.taxid_verdict;
  const taxId = customer.tax_ids?.data[0];
  if (taxId && (!verdict || verdict === 'unchecked' || customer.metadata.taxid_value !== taxId.value)) {
    verdict = (await recordVerdict(customerId, taxId))?.verdict;
  }
  if (verdict === 'fail') return { ok: false, why: 'Tax ID failed the registry check' };
  if (verdict === 'review' || verdict === 'unchecked') return { ok: false, why: 'Hold for a human look' };
  return { ok: true };
}

app.listen(4242);

Python (Flask)

# pip install stripe flask requests
import os
from datetime import datetime, timezone
from urllib.parse import quote

import requests
import stripe
from flask import Flask, request

stripe.api_key = os.environ["STRIPE_SECRET_KEY"]
HALPII = "https://taxid.halpii.com"
ROUTES = {"pe_ruc": "pe/ruc", "mx_rfc": "mx/rfc", "co_nit": "co/nit", "cr_tin": "cr/cedula"}
COUNTRY = {
    "cl_tin": "CL",
    "do_rcn": "DO",
    "ar_cuit": "AR",
    "br_cnpj": "BR",
    "ec_ruc": "EC",
    "uy_ruc": "UY",
    "py_ruc": "PY",
    "bo_tin": "BO",
    "ve_rif": "VE",
}


def check_tax_id(tax_type, value):
    if tax_type in ROUTES:
        url = f"{HALPII}/v1/{ROUTES[tax_type]}/{quote(value, safe='')}"
        params = None
    elif tax_type in COUNTRY:
        url, params = f"{HALPII}/v1/validate", {"country": COUNTRY[tax_type], "id": value}
    else:
        return None  # not a Latin American type: leave it to Stripe

    res = requests.get(
        url,
        params=params,
        headers={"Authorization": f"Bearer {os.environ['HALPII_TAXID_KEY']}"},
        timeout=15,
    )
    # 503: the registry did not answer (not billed). 429: daily allowance used.
    if res.status_code in (503, 429):
        return {"verdict": "unchecked", "reason": f"HTTP {res.status_code}", "level": ""}
    body = res.json()
    if res.status_code == 400:
        return {"verdict": "fail", "reason": body.get("error", ""), "level": body.get("verification_level", "")}
    res.raise_for_status()
    return {
        "verdict": body["assessment"]["verdict"],  # pass | review | fail
        "reason": " ".join(body["assessment"]["reasons"]),
        "level": body["verification_level"],
    }


def record_verdict(customer_id, tax_id):
    r = check_tax_id(tax_id["type"], tax_id["value"])
    if r is None:
        return None
    stripe.Customer.modify(
        customer_id,
        metadata={
            "taxid_verdict": r["verdict"],
            "taxid_level": r["level"],
            "taxid_value": tax_id["value"],
            "taxid_checked_at": datetime.now(timezone.utc).isoformat(),
            "taxid_reason": r["reason"][:500],
        },
    )
    return r


app = Flask(__name__)


@app.post("/stripe/webhook")
def webhook():
    try:
        event = stripe.Webhook.construct_event(
            request.data, request.headers.get("Stripe-Signature"), os.environ["STRIPE_WEBHOOK_SECRET"]
        )
    except (ValueError, stripe.SignatureVerificationError):
        return "", 400
    if event["type"] == "customer.tax_id.created":
        tax_id = event["data"]["object"]
        if tax_id.get("customer"):
            # In production, push this onto your job queue and return 200 right away.
            record_verdict(tax_id["customer"], tax_id)
    return "", 200

What to do with each verdict

AnswerMeaningSuggested action
PASSFound in the official registry and in good standing per the source.Invoice normally. Re-check periodically: status changes, and Stripe does not re-validate.
REVIEWNeeds a human look: format check only, not found in our latest copy, active but flagged (for example NO HABIDO in Peru), or any Mexican RFC.Hold the invoice or route it to a person. Read assessment.reasons; for format-only countries, check the official_lookup_url in the answer.
FAILInvalid check digit, malformed (HTTP 400), deregistered or not active, or on a blacklist.Ask the customer to confirm the number before you invoice. Do not "fix" it yourself.
HTTP 503The registry or our copy did not answer in time. Not billed and not counted against your quota. The response carries Retry-After: 120.Store unchecked and retry later. Never treat it as a pass or a fail.
HTTP 429Daily allowance used. Resets at 00:00 UTC.Store unchecked; retry after the reset or move to pay-as-you-go.
Keep the evidence. Store the verdict, the verification level and the date with the customer (the samples use metadata keys taxid_verdict, taxid_level and taxid_checked_at). Registry answers also carry source.data_as_of, the date of the registry copy behind the answer.

Try it

Every endpoint, field and error code is in the API reference. A no-cost API key comes with a daily allowance (see pricing), enough to wire up the webhook and test it against your own customers. Coverage and sources for each country are on the countries page.

This guide is general information, not legal, tax or accounting advice. HALPII Tax ID is an independent service run by HALPII S.A.C. It is not affiliated with or endorsed by Stripe, and it is not affiliated with or endorsed by SUNAT or any other tax authority or registry. Stripe's behavior is described from its public documentation as read on the date above; check the linked Stripe pages for the current version.