Displaying Card Logos with Gr4vy Secure Fields (TypeScript)

Overview

Gr4vy Secure Fields does not automatically display credit card logos in your checkout UI. Instead, the Secure Fields SDK detects the card scheme (Visa, Mastercard, American Express, etc.) as the customer types the card number and exposes that information through field events.

Your application is responsible for:

Listening for card number field events.
Reading the detected card scheme.
Displaying the corresponding card logo.

Note: Secure Fields can also render scheme icons inside the card-number field via showSchemeIcons on addCardNumberField. This guide covers the custom (outside-the-iframe) logo pattern. See Secure Fields events for event payloads.

Related: Secure Form vs Secure Fields.

Flow

Customer Types Card Number
            │
            ▼
Gr4vy Secure Fields
Detects Card Scheme
            │
            ▼
Input Event Fires
            │
            ▼
Application Receives
schema = "visa"
            │
            ▼
Update UI
Display Visa Logo

Architecture

┌───────────────────────────┐
│ Customer                  │
│ Types Card Number         │
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│ Gr4vy Secure Fields       │
│                           │
│ Detects Scheme            │
│  • visa                   │
│  • mastercard             │
│  • amex                   │
│  • discover               │
└─────────────┬─────────────┘
              │ input event
              ▼
┌───────────────────────────┐
│ Application               │
│                           │
│ event.schema = "visa"     │
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│ Card Logo Component       │
│                           │
│ Displays Visa SVG         │
└───────────────────────────┘

Example HTML

<div class="payment-form">
 
    <div id="card-number"></div>
 
    <img
        id="card-logo"
        src=""
        alt="Card Type"
        hidden
    />
 
</div>

TypeScript Example

Uses @gr4vy/secure-fields. The card-number input event exposes the detected scheme as schema (for example "visa"). For API-confirmed scheme (including co-branded networks), listen for card-details-changed, which uses scheme.

import SecureFields from "@gr4vy/secure-fields";
 
const secureFields = new SecureFields({
    gr4vyId: "<GR4VY_ID>",
    environment: "sandbox", // or "production"
    sessionId: "<CHECKOUT_SESSION_ID>"
});
 
const cardNumber = secureFields.addCardNumberField("#card-number", {
    placeholder: "Card number"
});
 
const logo = document.getElementById("card-logo") as HTMLImageElement;
 
cardNumber.addEventListener("input", (event) => {
 
    const schema = event.schema;
 
    if (!schema) {
        logo.hidden = true;
        return;
    }
 
    logo.src = `/assets/cards/${schema}.svg`;
    logo.hidden = false;
 
});

Using Gr4vy Hosted Icons

Instead of bundling your own icons, you can reference Gr4vy’s hosted SVG assets.

logo.src =
    `https://cdn.<gr4vy_id>.gr4vy.app/assets/icons/card-schemes/${schema}.svg`;

Example URLs:

https://cdn.demo.gr4vy.app/assets/icons/card-schemes/visa.svg
https://cdn.demo.gr4vy.app/assets/icons/card-schemes/mastercard.svg
https://cdn.demo.gr4vy.app/assets/icons/card-schemes/amex.svg

Recommended: Bundle Your Own Icons

For most production applications, bundling the SVGs with your frontend provides several advantages.

Example project structure:

src/
 ├── assets/
 │    └── cards/
 │         ├── visa.svg
 │         ├── mastercard.svg
 │         ├── amex.svg
 │         ├── discover.svg
 │         ├── diners.svg
 │         ├── jcb.svg
 │         ├── unionpay.svg
 │         └── generic.svg
 │
 └── components/
      └── PaymentForm.tsx

Benefits:

No network request for card icons
Faster rendering
Works offline
Full control over branding
Easy dark mode support
Consistent rendering across browsers

Creating a Card Logo Helper

const CARD_LOGOS: Record<string, string> = {
    visa: "/assets/cards/visa.svg",
    mastercard: "/assets/cards/mastercard.svg",
    amex: "/assets/cards/amex.svg",
    discover: "/assets/cards/discover.svg",
    diners: "/assets/cards/diners.svg",
    jcb: "/assets/cards/jcb.svg",
    unionpay: "/assets/cards/unionpay.svg"
};
 
export function getCardLogo(schema?: string): string {
 
    if (!schema) {
        return "/assets/cards/generic.svg";
    }
 
    return CARD_LOGOS[schema] ??
           "/assets/cards/generic.svg";
}

Usage:

cardNumber.addEventListener("input", (event) => {
    logo.src = getCardLogo(event.schema);
});

React Example

const [schema, setSchema] = useState<string>();
 
useEffect(() => {
 
    cardNumber.addEventListener("input", (event) => {
        setSchema(event.schema);
    });
 
}, []);
 
return (
    <>
        <div id="card-number" />
 
        <img
            src={getCardLogo(schema)}
            alt={schema ?? "Card"}
        />
    </>
);

Supported Card Schemes

Typical values returned by Gr4vy include:

Scheme	Logo
visa	Visa
mastercard	Mastercard
amex	American Express
discover	Discover
diners	Diners Club
jcb	JCB
unionpay	UnionPay
maestro	Maestro
elo	Elo
hipercard	Hipercard
mir	MIR

The exact list depends on the payment methods enabled in your Gr4vy account.

Recommended Integration Pattern

Secure Fields
       │
       ▼
Input Event
       │
       ▼
Read event.schema
       │
       ▼
Lookup SVG
       │
       ▼
Update <img>

This keeps the payment form PCI compliant while allowing the frontend to provide immediate visual feedback about the detected card type.

Best Practices

Display the logo only after a scheme has been confidently identified.
Show a generic card icon until a specific scheme is detected.
Bundle SVG assets with your application when possible.
Keep card logos outside of the Secure Fields iframe.
Avoid making network requests on every input event.
Use vector (SVG) assets for crisp rendering on high-DPI displays.
Gracefully fall back to a generic card icon for unknown or unsupported schemes.