n8n-nodes-n8ntools-pix-qrcode-generator

N8N Tools - Pix QR Code Generator

Generate Pix QR Codes for Brazilian instant payments with this N8N community node. Create both static and dynamic BR Code compliant QR codes for seamless payment integration.

✨ Features

• 📱 Static Pix QR Codes: Generate QR codes for fixed amount payments or donations
• 🔄 Dynamic Pix QR Codes: Generate QR codes for variable payments with amount validation
• 🇧🇷 BR Code Compliance: Full compliance with Banco Central do Brasil (BCB) EMV® QR Code specification
• 🔑 Multiple Key Types: Support for CPF, CNPJ, email, phone number, and random keys
• 🖼️ QR Image Generation: Output QR code images in Base64 format for direct display
• 💰 Flexible Amounts: Handle fixed amounts or donation-style (no amount) QR codes
• 📋 Transaction Details: Include payment descriptions and reference labels
• 🔒 Secure API: Powered by N8N Tools platform with usage tracking and validation

🚀 Quick Start

Installation

Install this node in your N8N instance:

Via Community Nodes (Recommended)

• Go to Settings > Community Nodes in your N8N interface
• Click Install a community node
• Enter n8n-nodes-n8ntools-pix-qrcode-generator
• Click Install

Via npm

npm install n8n-nodes-n8ntools-pix-qrcode-generator

Setup Credentials

• Sign up at N8N Tools and get your API key
• In N8N, create new N8N Tools API credentials
• Enter your API URL: https://api.n8ntools.io
• Enter your API key

📋 Available Operations

📱 Generate Static QR

Create QR codes for fixed payments or donations with optional amounts.

🔄 Generate Dynamic QR

Create QR codes for variable payments with mandatory amounts and enhanced validation.

💡 Usage Examples

Static QR Code for Donations

Create a QR code that allows customers to choose their own payment amount:

// Configuration
Operation: "Generate Static QR"
Merchant Name: "Minha ONG"
Merchant City: "São Paulo"
Pix Key: "[e-mail]"
Transaction Amount: 0 // Leave empty for donations
Additional Info: "Doação para causa social"
Transaction ID: "" // Optional

// Output
{
  "operation": "generateStatic",
  "success": true,
  "brCode": "[e-mail]0220Doação para causa social520400005303986580...",
  "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "pixKey": "[e-mail]",
  "creditsUsed": 1,
  "creditsRemaining": 99
}

Static QR Code for Fixed Payment

Create a QR code for a specific payment amount:

// Configuration
Operation: "Generate Static QR"
Merchant Name: "Café do João"
Merchant City: "Rio de Janeiro"
Pix Key: "11999887766"
Transaction Amount: 25.50
Additional Info: "Café expresso + pão de açúcar"
Transaction ID: "PEDIDO-001"

// Output
{
  "operation": "generateStatic", 
  "success": true,
  "brCode": "00020126580014br.gov.bcb.pix011311999887766...",
  "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "pixKey": "11999887766",
  "transactionAmount": 25.50,
  "creditsUsed": 1,
  "creditsRemaining": 98
}

Dynamic QR Code for E-commerce

Create a QR code for variable payment scenarios with mandatory amounts:

// Configuration
Operation: "Generate Dynamic QR"
Merchant Name: "Loja Virtual LTDA"
Merchant City: "Belo Horizonte"
Pix Key: "12.345.678/0001-90"
Transaction Amount: 149.90
Additional Info: "Compra Online #12345"
Transaction ID: "TXN-DYN-001"

// Output
{
  "operation": "generateDynamic",
  "success": true,
  "brCode": "00020126580014br.gov.bcb.pix011812.345.678/0001-90...",
  "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "pixKey": "12.345.678/0001-90",
  "transactionAmount": 149.90,
  "creditsUsed": 1,
  "creditsRemaining": 97
}

⚙️ Configuration Options

Operation Types

• Static QR: Best for donations, tips, or recurring payments
• Dynamic QR: Best for e-commerce, invoices, or specific transactions

Input Parameters

Common Parameters

• Merchant Name: Business or individual name (max 25 characters)
• Merchant City: Business location city (max 15 characters)
• Pix Key: Valid registered Pix key
• Additional Info: Payment description (optional)
• Transaction ID: Unique reference identifier (optional)

Transaction Amount

• Static QR: Optional (leave empty for donations)
• Dynamic QR: Required (must be greater than 0)

Output Options

• Output BR Code: Include the raw BR Code string in response
• Output QR Image: Include Base64 encoded QR code image

🔑 Supported Pix Key Types

CPF (Individuals)

Format: 123.456.789-00 or 12345678900
Example: "045.123.456-78"

CNPJ (Companies)

Format: 12.345.678/0001-90 or 12345678000190
Example: "11.222.333/0001-81"

Email Address

Format: [e-mail]
Example: "[e-mail]"

Phone Number

Format: [phone]
Example: "[phone]"

Random Key (EVP)

Format: UUID v4
Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

🛠️ Example Workflows

Restaurant Payment System

[Order Created] → [Calculate Total] → [Generate Static QR] → [Display QR Code] → [Payment Confirmation]

Donation Campaign

[Campaign Page] → [Generate Static QR (No Amount)] → [Display QR Code] → [Track Donations]

E-commerce Checkout

[Shopping Cart] → [Generate Dynamic QR] → [Email QR Code] → [Payment Webhook] → [Order Fulfillment]

Invoice Processing

[Invoice Data] → [Generate Dynamic QR] → [Send Invoice Email] → [Payment Tracking] → [Update Status]

📊 Technical Specifications

BR Code Standard

• EMV® QR Code: Full compliance with EMV® specification
• CRC16-CCITT-FALSE: Automatic checksum calculation
• Character Encoding: UTF-8 support for Portuguese characters
• Payload Format Indicator: Version 01 compliance

QR Code Generation

• Error Correction Level: Medium (M)
• Image Size: 300x300 pixels
• Output Format: PNG encoded as Base64 data URL
• Margin: 2 modules around QR code

🚨 Error Handling

The node includes comprehensive error handling with descriptive messages:

Validation Errors

{
  "error": "Merchant name must be 25 characters or less",
  "success": false,
  "operation": "generateStatic"
}

Parameter Errors

{
  "error": "Transaction amount is required for dynamic QR codes",
  "success": false,
  "operation": "generateDynamic"
}

QR Generation Errors

{
  "error": "Failed to generate QR code: Invalid BR Code format",
  "success": false,
  "operation": "generateStatic"
}

🔧 Troubleshooting

Common Issues

QR Code Not Scanning

• Ensure BR Code string is valid and complete
• Check that merchant name and city are within character limits
• Verify Pix key is properly registered and active

Invalid Pix Key

• CPF/CNPJ must be valid and registered with a bank
• Email/phone must be registered as Pix keys
• Random keys must be in valid UUID format

Character Limit Exceeded

• Merchant name: Maximum 25 characters
• Merchant city: Maximum 15 characters
• Additional info: Keep descriptions concise

Amount Formatting

• Use decimal format with dot separator (e.g., 100.50)
• Maximum 2 decimal places
• No currency symbols or thousands separators

💸 Pricing & Limits

• QR Code Generation: 1 credit per QR code generated
• Monthly Quotas: Based on your N8N Tools subscription plan
• API Rate Limits: Based on your subscription tier
• Usage Tracking: Built-in credit monitoring with remaining balance
• Cost per QR: Typically $0.01-$0.05 per QR code depending on plan

📈 Performance Tips

• Batch Processing: Generate multiple QR codes in sequence for bulk operations
• Image Optimization: Only generate images when needed for display
• BR Code Storage: Store BR Code strings for later QR image generation
• Caching: Cache generated QR codes for repeated transactions

🆘 Support

• Documentation: docs.n8ntools.io
• Issues: GitHub
• Discord: Community
• Email: [e-mail]

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by N8N Tools