A checkout form for Turkish customers looks like any other until the first invoice bounces. The buyer typed
"Kadikoy" as the tax office, entered an 11-digit number for an A.Ş., or gave a 0850 line that can't receive the SMS
with the delivery code. None of this throws an error at checkout; it shows up days later in accounting or customer
support.
I build VeriApi.Pro, a data API for Turkey, and this is the checklist we use for
shop forms. Each section has a check you can run locally and, where local code isn't enough, an API call. Everything
below was run against the live API with PHP 8.3 and Node 22.
The fields
| Field | Individual invoice | Corporate invoice |
|---|---|---|
| Name | Full name | Company name (unvan) |
| ID | TCKN, 11 digits (optional on e-Arşiv) | VKN, 10 digits, or TCKN for sole proprietors |
| Tax office | — | Required (vergi dairesi) |
| Phone | Mobile, for SMS | Mobile or landline |
| Address | Province, district, neighbourhood, postcode | Same |
| Refund IBAN | Optional | Optional |
1. VKN and TCKN are different algorithms
A company tax number (VKN) has 10 digits; a personal ID (TCKN) has 11. Sole proprietors invoice with their TCKN, so
a corporate form has to accept both, and pick the algorithm by length. The VKN check digit:
function isValidVkn(no) {
if (!/^\d{10}$/.test(no)) return false;
const d = [...no].map(Number);
let sum = 0;
for (let i = 0; i < 9; i++) {
const t = (d[i] + 9 - i) % 10;
sum += t === 9 ? 9 : (t * 2 ** (9 - i)) % 9;
}
return (10 - (sum % 10)) % 10 === d[9];
}
isValidVkn("1234567890"); // true
isValidVkn("1234567891"); // false
For the TCKN, remember the negative-modulo bug (((x % 10) + 10) % 10, covered in
my previous post on Turkish-specific bugs).
Two traps the checksum won't catch:
-
Special values. e-Arşiv invoices commonly use
11111111111for a consumer who doesn't give an ID and2222222222for a foreign buyer. Both fail the checksum. If your form rejects them, your accountant will ask why the "no ID" option doesn't work. Handle them before running the algorithm. - Number type vs company type. An A.Ş. (joint-stock) or Ltd. Şti. (limited) company is a legal entity and always has a 10-digit VKN. An 11-digit number next to "A.Ş." is wrong even if the digits pass.
2. The tax office is free text, and the invoice needs the official name
Customers type Kadikoy, Kadıköy VD, kadıköy v.d. or just Merkez. There are 858 tax offices plus branch
offices, several share a name across provinces, and the e-invoice wants the official name.
Checking the three fields together catches most of it in one request (free plan):
curl -H "X-API-Key: $VERIAPI_KEY" \
"https://api.veriapi.pro/v1/dogrula/firma?vergi_no=1234567890&vergi_dairesi=Kadikoy&unvan=%C3%96rnek%20Yaz%C4%B1l%C4%B1m%20Limited%20%C5%9Eirketi"
{
"sonuc": "gecerli",
"kontroller": [
{ "alan": "vergi_no", "durum": "gecerli", "mesaj": "VKN algoritmaya uygun" },
{ "alan": "unvan", "durum": "bilgi", "mesaj": "Unvandan şirket türü: Limited şirket" },
{ "alan": "vergi_dairesi", "durum": "gecerli", "mesaj": "Kadıköy Vergi Dairesi Müdürlüğü (İstanbul)" }
],
"duzeltilmis": {
"unvan": "ÖRNEK YAZILIM LTD. ŞTİ.",
"vergi_dairesi": "Kadıköy Vergi Dairesi Müdürlüğü",
"vergi_dairesi_kodu": "34272",
"il": "İstanbul"
}
}
duzeltilmis ("corrected") gives you what to print on the invoice. When a tax office name exists in more than one
province, the response returns a warning plus the candidates, so you can ask the user to pick one.
What it can't tell you: whether the company is real and active. That needs the Revenue Administration's (GİB) own
taxpayer query, which requires authorised integration. The check is for typos and inconsistent data at the moment of
ordering.
3. Phone: store E.164, and ask for a mobile when you send SMS
The same number arrives as 05321234567, 5321234567, +90 532 123 45 67 and 0090…. Normalise to E.164 before
storing or you'll get duplicate customers. And if the delivery code goes out by SMS, check the type: 0850
numbers are VoIP/corporate lines and landlines start with an area code (0216, 0312…).
{ "e164": "+905321234567", "ulusal": "0532 123 45 67", "tur": "MOBILE" }
{ "e164": "+908501234567", "ulusal": "0850 123 4567", "tur": "VOIP" }
{ "e164": "+902161234567", "ulusal": "(0216) 123 45 67", "tur": "FIXED_LINE", "yer": "İstanbul (Anadolu)" }
Don't show the user an operator name: with number portability, a 0532 line may have moved to another carrier.
4. Address: one postcode, several neighbourhoods
Turkish postcodes are assigned per neighbourhood (mahalle), not per street, and one code can cover more than one
neighbourhood. 34722 is both Eğitim and Hasanpaşa in Kadıköy:
{
"posta_kodu": "34722",
"yerler": [
{ "il": "İstanbul", "ilce": "Kadıköy", "mahalle": "Eğitim" },
{ "il": "İstanbul", "ilce": "Kadıköy", "mahalle": "Hasanpaşa" }
]
}
So autofill the province and district from the code, but offer the neighbourhoods as a choice rather than picking
the first one. Keep the API key on the server with a small proxy:
<?php
// postcode.php?code=34722: a tiny proxy so the API key never reaches the browser
header('Content-Type: application/json; charset=utf-8');
$code = preg_replace('/\D/', '', $_GET['code'] ?? '');
if (strlen($code) !== 5) { http_response_code(400); echo '{"places":[]}'; exit; }
$ctx = stream_context_create(['http' => [
'header' => "X-API-Key: " . getenv('VERIAPI_KEY') . "\r\nUser-Agent: myshop/1.0",
'timeout' => 5, 'ignore_errors' => true,
]]);
$body = @file_get_contents("https://api.veriapi.pro/v1/posta-kodu?kod=$code", false, $ctx);
$data = $body ? json_decode($body, true) : null;
header('Cache-Control: public, max-age=86400'); // postcodes rarely change
echo json_encode(['places' => $data['veri']['yerler'] ?? []], JSON_UNESCAPED_UNICODE);
<input id="postcode" inputmode="numeric" maxlength="5">
<input id="province"><input id="district"><select id="neighbourhood"></select>
<script>
const $ = (id) => document.getElementById(id);
$("postcode").addEventListener("change", async () => {
const res = await fetch("/postcode.php?code=" + encodeURIComponent($("postcode").value));
const { places } = await res.json();
if (!places.length) return; // unknown code: let the user type
$("province").value = places[0].il;
$("district").value = places[0].ilce;
$("neighbourhood").replaceChildren(...places.map((p) => new Option(p.mahalle, p.mahalle)));
});
</script>
new Option() instead of innerHTML keeps API data from being parsed as HTML.
For the dropdowns themselves, Turkey has 81 provinces and 973 districts; the lists copied between projects are
often missing newer districts. /v1/konumlar/iller and /v1/konumlar/iller/{province}/ilceler return the current
list with stable slugs. Store the slug, not the display name. The
province / district page and the
postcode page have the details.
5. Refund IBAN: MOD-97 in the browser, bank name from the server
A regex like ^TR\d{24}$ accepts typos. The MOD-97 check is short enough to run as the user types:
function isValidTrIban(input) {
const iban = input.replace(/\s+/g, "").toUpperCase();
if (!/^TR\d{24}$/.test(iban)) return false;
const moved = iban.slice(4) + iban.slice(0, 4);
const digits = moved.replace(/[A-Z]/g, (c) => c.charCodeAt(0) - 55);
let rem = 0;
for (const ch of digits) rem = (rem * 10 + Number(ch)) % 97;
return rem === 1;
}
isValidTrIban("TR95 0006 4000 0000 1234 5678 90"); // true
isValidTrIban("tr950006400000001234567891"); // false
Showing the bank name next to the field ("T. İŞ BANKASI A.Ş.") is a good second signal for the user: if they bank
elsewhere, they've typed the wrong IBAN. The bank code is characters 5–9; the
IBAN endpoint maps it to the bank.
One thing no API can do: confirm that the IBAN belongs to the person who typed it. Only the bank knows that.
6. Putting it together on the server
Browser checks give fast feedback; the decision is made on the server. If the API is unreachable, the order should
still go through with the check skipped. A lost sale costs more than an unchecked phone number.
<?php
function veriapi(string $path, array $query): ?array {
$url = 'https://api.veriapi.pro' . $path . '?' . http_build_query($query);
$ctx = stream_context_create(['http' => [
'header' => "X-API-Key: " . getenv('VERIAPI_KEY') . "\r\nUser-Agent: myshop/1.0",
'timeout' => 5,
'ignore_errors' => true,
]]);
$body = @file_get_contents($url, false, $ctx);
$json = $body ? json_decode($body, true) : null;
return $json['veri'] ?? null; // null = API unreachable: don't block the order
}
function check_order(array $in): array {
$errors = [];
$clean = [];
// Phone: store E.164, require a mobile number for SMS
$tel = veriapi('/v1/telefon/bilgi', ['numara' => $in['phone'] ?? '']);
if ($tel && !$tel['gecerli']) {
$errors['phone'] = 'Please enter a valid phone number.';
} elseif ($tel && $tel['tur'] !== 'MOBILE') {
$errors['phone'] = 'We send the delivery code by SMS; please enter a mobile number.';
}
$clean['phone'] = $tel['e164'] ?? ($in['phone'] ?? '');
// Corporate invoice: tax number + tax office + company name, checked together
if (($in['invoice_type'] ?? '') === 'corporate') {
$firm = veriapi('/v1/dogrula/firma', [
'vergi_no' => $in['tax_no'] ?? '',
'vergi_dairesi' => $in['tax_office'] ?? '',
'unvan' => $in['company'] ?? '',
]);
foreach ($firm['kontroller'] ?? [] as $c) {
if ($c['durum'] === 'gecersiz') $errors['tax_no'][] = $c['mesaj'];
}
$clean['tax_office'] = $firm['duzeltilmis']['vergi_dairesi'] ?? ($in['tax_office'] ?? '');
$clean['company'] = $firm['duzeltilmis']['unvan'] ?? ($in['company'] ?? '');
}
// Refund IBAN (optional)
if (!empty($in['refund_iban'])) {
$iban = veriapi('/v1/iban/dogrula', ['iban' => $in['refund_iban']]);
if ($iban && !$iban['gecerli']) $errors['refund_iban'] = 'IBAN: ' . $iban['hata'];
$clean['refund_iban'] = $iban['iban'] ?? $in['refund_iban'];
$clean['refund_bank'] = $iban['banka']['ad'] ?? null;
}
return [$errors, $clean];
}
With a clean order (0532 123 45 67, VKN 1234567890, tax office Kadikoy, "Örnek Yazılım Limited Şirketi", a
lower-case IBAN with spaces), $errors is empty and $clean is ready for the invoice:
{
"phone": "+905321234567",
"tax_office": "Kadıköy Vergi Dairesi Müdürlüğü",
"company": "ÖRNEK YAZILIM LTD. ŞTİ.",
"refund_iban": "TR950006400000001234567890",
"refund_bank": "T. İŞ BANKASI A.Ş."
}
With a 0850 number, an 11-digit number for an A.Ş. and a mistyped IBAN:
{
"phone": "We send the delivery code by SMS; please enter a mobile number.",
"tax_no": [
"Kontrol haneleri tutmuyor",
"Anonim şirket tüzel kişidir, 10 haneli VKN kullanır; 11 haneli TCKN yalnızca şahıs mükellefte olur"
],
"refund_iban": "IBAN: Kontrol haneleri tutmuyor (MOD-97)"
}
The API's messages are in Turkish, which is usually what you want on a Turkish storefront. For an English UI, switch
on alan (field) and durum (status) and write your own text.
7. Bonus: shipping weight (desi)
Turkish carriers charge by desi: width × length × height in cm ÷ 3000 for domestic shipments (international often
uses 5000), compared with the real weight in kg, and the larger one wins. A 40 × 30 × 20 cm box weighing 5 kg is
8 desi, so you pay for 8, not 5. /v1/kargo/desi?en=40&boy=30&yukseklik=20&agirlik=5 returns both values and
which one is charged. Check your carrier's divisor; a few use 6000 for air freight.
Cleaning an existing customer list
If you already have thousands of customers with phone numbers in three formats, the bulk endpoints take 1,000 tax
numbers or phone numbers (or 500 company records) per request: POST /v1/dogrula/toplu,
/v1/telefon/toplu-dogrula, /v1/dogrula/firma/toplu. These are on paid plans; send personal data in the POST body,
not in the URL.
Summary
| Field | Local check | Needs data |
|---|---|---|
| VKN / TCKN | Check digits; allow 11111111111 / 2222222222; 10 digits for A.Ş. / Ltd. |
Tax office list |
| Tax office | — | Official name and code |
| Phone | — | Type (mobile / landline / 0850), E.164 |
| Postcode | 5 digits | Province, district, list of neighbourhoods |
| IBAN | MOD-97, TR + 24 digits |
Bank name |
| Shipping | desi = W × L × H ÷ 3000 | Carrier's divisor |
Everything in sections 1–5 and 7 works on the free plan (500 request units a day, no card). There's a Turkish summary
of the same checks on our e-commerce page, and the
documentation lists every endpoint. If your Turkish checkout has a
field that breaks in a way I haven't covered, tell me in the comments.
Top comments (0)