Skip to main content

Merchant Snippet Integration

Complete guide to the FinMatch SDK snippet code that merchants add to their websites.

Overview​

The FinMatch SDK snippet is a JavaScript module that merchants embed in their website's <head> section to enable FinMatch finance functionality. The snippet URL includes the merchant ID and is environment-specific.

Snippet Code Format​

Production Environment​

<script src="https://storage.googleapis.com/finmatch-finance-marketing-assets/p/scripts/finmatch-sdk.js?merchantID=M000101&v=1.0" type="module" async></script>

Staging Environment​

<script src="https://storage.googleapis.com/finmatch-finance-marketing-assets/s/scripts/finmatch-sdk.js?merchantID=M000101&v=1.0" type="module" async></script>

Test Environment​

<script src="https://storage.googleapis.com/finmatch-finance-marketing-assets/t/scripts/finmatch-sdk.js?merchantID=M000101&v=1.0" type="module" async></script>

Snippet URL Structure​

https://storage.googleapis.com/finmatch-finance-marketing-assets/{environment}/scripts/finmatch-sdk.js?merchantID={merchantId}&v=1.0

Components:

  • Base URL: https://storage.googleapis.com/finmatch-finance-marketing-assets/
  • Environment Path: p/ (production), s/ (staging), or t/ (test)
  • Script Path: scripts/finmatch-sdk.js
  • Query Parameters:
    • merchantID: The merchant's FinMatch ID (format: MXXXXXX or FM-XXXX-XXXX-XXXX)
    • v: Version number (currently 1.0)

Where to View Snippet Code​

1. Merchant Details Page​

When viewing a merchant's details:

  1. Navigate to Merchants page
  2. Click on a merchant's company name
  3. Scroll to App Information section
  4. The snippet code is displayed in the Snippet field

2. Edit Merchant Modal​

When editing a merchant:

  1. Click "⋯" (three dots) → "✏️ Edit" on any merchant
  2. The Integration Snippet field shows the current snippet code
  3. Changing the Environment dropdown updates the snippet code automatically

3. Integration Guide Modal​

To send the snippet to a merchant:

  1. View merchant details
  2. Click "Send Integration Guide" button
  3. The merchant detail page displays the snippet code
  4. Enter recipient email and send

Snippet Generation​

Frontend Function​

Location: admin/js/merchants.js → generateSnippetCode()

function generateSnippetCode(merchantId, environment) {
  // Map environment to path: t=test, s=staging, p=production
  const envPath = environment === 't' ? 't' : environment === 's' ? 's' : 'p';
  return `<script src="https://storage.googleapis.com/finmatch-finance-marketing-assets/${envPath}/scripts/finmatch-sdk.js?merchantID=${merchantId}&v=1.0" type="module" async></script>`;
}

Parameters:

  • merchantId: Merchant's FinMatch ID (supports both MXXXXXX and FM-XXXX-XXXX-XXXX formats)
  • environment: Environment code ('p', 's', or 't')

Returns: Complete HTML <script> tag ready to embed

Environment Mapping​

Environment CodeEnvironment NameURL Path
pProduction/p/scripts/
sStaging/s/scripts/
tTest/t/scripts/

Merchant ID Format Support​

The snippet generation supports both merchant ID formats:

  • New Format: MXXXXXX (e.g., M000101)
  • Legacy Format: FM-XXXX-XXXX-XXXX (e.g., FM-0294-8617-5039)

Both formats work identically in the snippet URL.

Where Snippet Code is Displayed​

1. Merchant Details Page​

Location: admin/merchants/index.html → App Information section

Element: #detailSnippet

Code Reference: admin/js/merchants.js → showMerchantDetails()

const env = merchant.environment || 'p';
const snippetCode = generateSnippetCode(merchant.id, env);
document.getElementById('detailSnippet').innerHTML = `<code>${snippetCode}</code>`;

2. Edit Merchant Modal​

Location: admin/merchants/index.html → Edit Merchant Modal

Element: #editSnippetDisplay

Code Reference: admin/js/merchants.js → editMerchant()

  • Displays snippet when merchant is loaded
  • Updates automatically when environment changes
  • Uses updateSnippetDisplay() function

3. Integration Guide Modal​

Location: admin/js/merchants.js → openSendIntegrationGuideModal()

Element: #integrationSnippet

  • Pre-filled with current merchant's snippet
  • Can be copied or sent via email

Dynamic Updates​

Environment Change​

When the environment is changed in the edit form:

  1. updateSnippetDisplay() function is called
  2. Snippet code is regenerated with new environment
  3. Display is updated immediately

Code Reference: admin/js/merchants.js → updateSnippetDisplay()

Implementation Details​

Storage Location​

The FinMatch SDK files are stored in Google Cloud Storage:

  • Bucket: finmatch-finance-marketing-assets
  • Path Structure: {environment}/scripts/finmatch-sdk.js
  • CORS: Configured to allow access from merchant domains

CORS Configuration​

Merchant domains are automatically added to CORS policy when merchants are created. See Merchant ID Architecture for details.

Version Parameter​

The v=1.0 parameter allows for future versioning:

  • Can be incremented to force cache refresh
  • Allows gradual rollout of SDK updates
  • Currently set to 1.0 for all merchants

Best Practices​

  1. Always Use HTTPS - The snippet URL uses HTTPS for security
  2. Place in <head> - Add the snippet in the website's <head> section
  3. Use Correct Environment - Match the environment to the merchant's setup
  4. Keep Merchant ID Secure - Don't expose merchant IDs unnecessarily
  5. Test Before Production - Use staging/test environments for testing

Troubleshooting​

Snippet Not Loading​

Check:

  1. Merchant domain is in CORS whitelist
  2. Environment path matches merchant's environment
  3. Merchant ID is correct format
  4. Browser console for errors

Wrong Environment​

Solution: Update merchant's environment in the admin dashboard, then regenerate snippet code.

CORS Errors​

Solution: Verify merchant domain is in CORS policy. See Merchant ID Architecture for CORS update process.