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
| Country | Stripe type | What Stripe checks | Changes Stripe Tax?* | What HALPII Tax ID checks |
|---|---|---|---|---|
| Peru | pe_rucPeruvian RUC number | Format only | Yes | Official registry Legal name, status, HABIDO condition, fiscal address · daily copy |
| Colombia | co_nitColombian NIT number | Format only | No | Official registry Legal name, commercial registration status, last renewal · live |
| Mexico | mx_rfcMexican RFC number | Format only | No | Format + tax-authority lists Format, check digit, SAT list status (never "active") · periodic copy |
| Chile | cl_tinChilean TIN | Format only | Yes | Official registry Legal name and status · periodic copy |
| Costa Rica | cr_tinCosta Rican tax ID | Format only | No | Official registry Hacienda status, tax regime, moroso / omiso, activities · live (beta) |
| Dominican Republic | do_rcnDominican RCN number | Format only | No | Official registry Legal name and status (RNC); format check for other ID types · daily copy |
| Argentina | ar_cuitArgentinian tax ID number | Format only | No | Format only Structure and check digit, offline |
| Brazil | br_cnpjBrazilian CNPJ number | Format only | No | Format only Structure and check digit, offline |
| Ecuador | ec_rucEcuadorian RUC number | Format only | No | Format only Structure and check digit, offline |
| Uruguay | uy_rucUruguayan RUC number | Format only | Yes | Format only Structure and check digit, offline |
| Paraguay | py_rucParaguayan RUC number | Format only | No | Format only Structure and check digit, offline |
| Bolivia | bo_tinBolivian tax ID | Format only | No | Format only Structure and check digit, offline |
| Venezuela | ve_rifVenezuelan RIF number | Format only | No | Format 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_tinanduy_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:
- When the tax ID is saved. Listen for
customer.tax_id.created("Occurs whenever a tax ID is created for a customer"). Itsdata.objectis a Tax ID object withtype,value,countryandcustomer. Call our API and store the verdict in the customer's metadata. - 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 toinvoice.createdbefore 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
| Answer | Meaning | Suggested action |
|---|---|---|
| PASS | Found in the official registry and in good standing per the source. | Invoice normally. Re-check periodically: status changes, and Stripe does not re-validate. |
| REVIEW | Needs 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. |
| FAIL | Invalid 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 503 | The 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 429 | Daily allowance used. Resets at 00:00 UTC. | Store unchecked; retry after the reset or move to pay-as-you-go. |
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.