Collect Cards Securely: NX Payment Widget Setup & Guide 💳✨

Accepting card details on your restaurant's website should be simple, smooth, and 100% secure! With the NX Payment Widget, guests can easily enter their card information right on your site. Behind the scenes, the sensitive card details go directly to Datacap (NX's payment processor) in exchange for a secure, one-time card token—meaning actual card numbers never touch your website code or servers!

This guide walks restaurant owners, web managers, and developers through adding the NX Payment Widget to your site and listening for secure card tokens.

What is the NX Payment Widget? 🤔

The NX Payment Widget is an embeddable "Add a Card" form built for your venue's website.

How It Works: A guest enters their card number, expiration date, and CVV. The widget processes this information securely and returns a checkmark along with the card brand and last 4 digits.
Developer Integration Required: Unlike our Plug-and-Play Waitlist or Reservation widgets, this widget requires a small amount of JavaScript code written by a web developer to catch the token and use it on your backend.

⚠️ Important Developer Note: This widget only tokenizes a card. It does not charge money, save the card permanently to a profile, or attach the card to an order automatically. Your website developer must catch the generated token and send it to your backend payment processing API!

Prerequisites Before Setup 📋

Before adding the widget to your website, make sure you have:

🆔 Your Venue Credentials: Your venue's Venue ID or Short Code.
💳 NX Pay Merchant Account: A default merchant account configured in NX Portal with e-commerce enabled. (If this is missing, the widget displays a paused message and will not open the form).
💻 A Web Developer: Someone who can paste the snippet into your site's HTML and write a short JavaScript listener to handle the token.

Part 1: Adding the Widget to Your Website 🌐

To place the widget on your site, add the following snippet to your website's HTML:

HTML

<nx-payment venue-short-code="YOUR-SHORT-CODE"></nx-payment>
<script src="https://cdn.nxapp.net/widgets/payment-widget.js"></script>

Important: Replace YOUR-VENUE-SHORT-CODE with your actual Venue Short Code. You can obtain your Venue Short Code from the NX Portal > Venue > General Settings. If the Venue Short Code is entered incorrectly, the widget will display a "Online card entry isn't available for this venue right now." notice.

Part 2: What Your Guests See & Do 🛒

When a guest accesses the widget on your webpage, they see a clean card titled "Add a Card":

Field 📝	Guest Input 💡	Automatic Validation 🔍
Card Number	Card number (auto-formats with spaces as typed)	Performs Luhn verification via Datacap. Detects and displays card brand logo/name (VISA, MASTERCARD, AMEX, DISCOVER, JCB, DINERS).
Expiration	`MM / YY`	Verifies a valid, non-expired date.
CVV (or CID)	3-digit security code (4 digits for Amex)	Verifies digit count based on card brand.

The Add Card button remains disabled until all fields pass validation. Once clicked:

Success: Displays a green checkmark, "Card Added", and the card brand/last 4 digits (e.g., "VISA card ending in 1111").
Error: Displays an error message and a Try Again button to reset the form.

Part 3: Catching the Token (For Web Developers) 🧑‍💻

When tokenization succeeds, the <nx-payment> element fires a custom JavaScript event named tokenized containing card metadata inside event.detail:

JavaScript

document.querySelector('nx-payment').addEventListener('tokenized', (event) => {
  const { token, last4, expMonth, expYear, brand } = event.detail;
  
  // Send `token` to your backend server to create a check or store payment method!
});

If validation or tokenization fails, a tokenizeError event fires with the error description string:

JavaScript

document.querySelector('nx-payment').addEventListener('tokenizeError', (event) => {
  console.error('Tokenization failed:', event.detail);
});

Part 4: Customizing Widget Styles 🎨

Match the widget to your website's branding using CSS custom properties! Apply styling variables directly to the <nx-payment> tag in your stylesheet:

CSS

nx-payment {
  --nx-primary: #c8102e;         /* Button and accent color */
  --nx-primary-hover: #a10d25;   /* Button hover state */
  --nx-radius: 4px;              /* Corner rounding */
  --nx-font: 'Lato', sans-serif; /* Typography font */
  --nx-surface: #ffffff;         /* Card background color */
  --nx-border: #e0e0e0;          /* Input border color */
  --nx-text: #333333;            /* Primary text color */
  --nx-muted: #777777;           /* Placeholder text color */
  --nx-error: #cc0000;           /* Error alert color */
  --nx-success: #2e7d32;         /* Success checkmark color */
}

📌 Technical Note for Developers: Unlike our Waitlist and Reservation widgets, the Payment Widget does not use Shadow DOM. This allows Datacap's secure tokenization script to locate form fields directly.

Troubleshooting & Common Questions 🔍

Problem / Symptom 💡	Likely Cause 🔍	Solution / Fix 🛠️
Widget shows a configuration error immediately	Missing or incorrect `venue-id` / `venue-short-code`.	Verify the embed code against your venue's real Venue ID in NX Portal.
Widget shows a paused message and hides the form	Venue merchant account lacks Datacap e-commerce enablement.	Contact NX Support to verify Datacap e-commerce settings on your merchant account.
"Add Card" stays stuck on "Loading..."	Datacap payment script failed to load over network.	Refresh browser page; verify firewall/network settings aren't blocking external scripts.
Nothing happens after "Card Added" displays	Missing JavaScript `tokenized` event listener.	Ensure your web developer has added the event listener script detailed in Part 3.

Need Additional Support? 💬

If you need assistance configuring your merchant processing or obtaining script URLs, reach out directly to NX Restaurant Support anytime! We're always happy to help keep your web checkout running smoothly. 🌟