When a checkout form accepts a card number, the first useful question is often not whether a payment will succeed. It is whether the input has a plausible length, a recognizable network, and a checksum that is worth sending to the next step.
Those checks improve feedback, but they are easy to overstate. A brand detector is not a payment gateway, a fraud engine, or proof that a card exists. This tutorial uses credit-card-brand-detector to build a small Node.js validation boundary while keeping those limits visible.
TL;DR
Install the published npm package, pass it synthetic test numbers, and inspect the result:
mkdir card-check-demo
cd card-check-demo
npm init -y
npm install credit-card-brand-detector@1.0.1
Then create check-card.js:
const { validateCreditCard } = require("credit-card-brand-detector");
const result = validateCreditCard("4532 0151 1283 0366");
console.log(result);
The expected shape is an object containing isValid: true and bandeira: "Visa" for this repository's documented synthetic example. The package also recognizes several other networks, including Mastercard, American Express, Discover, Elo, Hipercard, and Aura.
Prerequisites
You need:
- Node.js 12 or newer, matching the package's declared engine range.
- npm.
- A terminal and a directory where
package.jsoncan be created. - Synthetic or official test numbers. Never paste a real primary account number into a tutorial, shell history, issue, or log.
The repository is MIT licensed. The current npm latest dist-tag is 1.0.1, while the checked-out repository package metadata reports 1.0.0. Pinning the published package in this example makes the installation reproducible and keeps the difference visible.
1. Install the detector
Start with a clean directory so the example has no hidden dependency on the source checkout:
mkdir card-check-demo
cd card-check-demo
npm init -y
npm install credit-card-brand-detector@1.0.1
The package has one runtime dependency according to its published metadata. Its public API exports validateCreditCard, detectBrand, getBrand, and luhnValidation.
For a form or API boundary, validateCreditCard is the most useful starting point because it combines brand detection with a Luhn checksum result. Use detectBrand alone when you need presentation only, such as showing a network icon after the user types a prefix.
2. Run a minimal check
Create check-card.js with a number used by the project's own examples:
const { validateCreditCard } = require("credit-card-brand-detector");
const cardNumber = "4532 0151 1283 0366";
const result = validateCreditCard(cardNumber);
console.log({
input: cardNumber,
validForBasicChecks: result.isValid,
brand: result.bandeira,
});
Run it:
node check-card.js
The package removes non-digit characters before checking the number, so spaces and hyphens are accepted. For the documented Visa example, the result identifies the network and passes the checksum.
That normalization is convenient, but it is not a reason to accept arbitrary input silently. Your application should still enforce its own input type, maximum length, and logging policy before calling the library.
3. Make invalid input visible
A useful boundary distinguishes an input that fails basic checks from a value that the payment provider later declines:
const { validateCreditCard } = require("credit-card-brand-detector");
function inspectCardInput(cardNumber) {
if (typeof cardNumber !== "string") {
return { ok: false, reason: "card number must be text" };
}
const result = validateCreditCard(cardNumber);
if (!result.isValid) {
return {
ok: false,
reason: "checksum or length check failed",
brand: result.bandeira,
};
}
if (!result.bandeira) {
return { ok: false, reason: "network not recognized" };
}
return { ok: true, brand: result.bandeira };
}
console.log(inspectCardInput("5555 5555 5555 4444"));
console.log(inspectCardInput("5555 5555 5555 4445"));
The first value is a synthetic Mastercard example from the repository's tests. The second keeps a similar shape but fails the checksum. The library can still return a detected brand when isValid is false because brand matching and Luhn validation are separate operations. That is why callers should inspect both fields.
4. Verify the behavior with tests
For a small integration test, use Node's built-in assertions so the application test does not depend on Jest:
const assert = require("node:assert/strict");
const { validateCreditCard, detectBrand } = require("credit-card-brand-detector");
assert.deepEqual(validateCreditCard("4532015112830366"), {
isValid: true,
bandeira: "Visa",
});
assert.equal(detectBrand("5555555555554444"), "Mastercard");
assert.equal(validateCreditCard("5555555555554445").isValid, false);
console.log("basic card-input checks passed");
Save that as check-card.test.js and run it with:
node check-card.test.js
The upstream checkout provides a larger Jest suite. In a fresh checkout of the public repository, npm ci completed and npm test passed 34 tests. The repository also includes test cases for Visa, Mastercard, American Express, Diners Club, Discover, EnRoute, JCB, Voyager, Hipercard, and Aura.
Why the two checks are separate
The implementation first strips non-numeric characters and rejects values outside its 13-to-19-digit length range. It then determines a brand from known prefixes and runs the Luhn algorithm over the cleaned digits.
These checks answer different questions:
- Brand detection asks which network pattern the prefix resembles.
- Luhn asks whether the digits satisfy a checksum used by many payment numbers.
- A payment processor asks whether the account, authorization, merchant, amount, and transaction context are acceptable.
Passing the first two does not answer the third. Keep the library at the client or API input-validation layer, then send payment data only through a processor and integration designed for handling it.
Failure modes and security boundaries
The result is valid but payment still fails
That is expected. The package does not contact an issuer, authorize a transaction, check funds, or detect fraud. Treat isValid as a local plausibility result, not an authorization result.
A recognized brand is returned for an invalid number
That is also expected from this API shape. Prefix matching can succeed while Luhn or length validation fails. Require both isValid and a non-null brand when your workflow needs both.
Formatting is accepted too broadly
The implementation removes every non-digit character. Decide whether that behavior matches your product. A stricter API may reject unexpected characters before calling the package, especially when input is received from machine clients rather than a human form.
Sensitive data appears in logs
Do not log the full input or include it in telemetry. Prefer a redacted value, a request identifier, and the validation reason. Use synthetic numbers in tests and documentation. Do not store card numbers in application databases unless your compliance design explicitly requires it.
The package does not cover a network
Prefix ranges change and regional networks differ. Treat the supported-brand list as a project feature, not a complete industry registry. Read the source implementation and add application-level tests before relying on a network-specific rule.
FAQ
Does this package process payments?
No. It performs local brand detection and Luhn-style validation only.
Can I use real card numbers in tests?
Use provider-approved test values or synthetic values. Never put production card numbers in source control, logs, documentation, or chat.
Should I call detectBrand or validateCreditCard?
Use detectBrand for display-only hints. Use validateCreditCard when you need the checksum result as well, and inspect both returned fields.
Is Luhn validation enough for checkout?
No. It is an early input check. Payment authorization, tokenization, fraud controls, and compliance belong to the payment architecture and provider you choose.
Takeaway
credit-card-brand-detector is useful when you need a small, dependency-light Node.js boundary for card-number formatting, network hints, and checksum feedback. The safe integration pattern is equally small: use synthetic test data, check both isValid and bandeira, avoid logging sensitive input, and never confuse local validation with payment authorization.
What would you add next to this boundary: stricter input normalization, provider test fixtures, or redaction checks for application logs?
AI assistance disclosure: AI helped organize and edit this tutorial. The repository README, source implementation, package metadata, license, npm metadata, and public test results were checked against the current public sources before publication.
Top comments (0)