Generate a Payment Form

Overview

Create payment forms using Deets with two flexible approaches. Choose the method that best fits your workflow and technical requirements.

💡 Two Ways to Generate Forms: Use the visual Checkout Customizer for quick setup, or the Payment Generator API for programmatic control and automation.

Time to complete: ~10-15 minutes

---

Choose Your Approach

🎨 Visual Customizer (Recommended for Quick Setup)

Best for: Testing, prototyping, one-time setups, and non-technical users

Benefits:

• Visual interface for styling
• Real-time preview
• No coding required
• Quick form generation

→ Use the Checkout Customizer

The visual customizer provides an intuitive interface where you can:

• Configure form appearance and styling
• Set up example transaction data
• Generate forms with custom branding
• Get both base URLs and pre-configured URLs

⚡ API Generation (Recommended for Developers)

Best for: Dynamic scenarios, automated workflows, custom integrations, and production systems

Benefits:

• Programmatic form creation
• Server-side generation for security
• Bulk form generation
• Custom integrations
• Advanced configuration options

Continue reading below for API implementation details

---

API-Based Form Generation

For automated or programmatic form generation, use the Deets Payment Generator API to create payment forms on-demand with complete control over configuration.

API Endpoints

Environment	Endpoint
Production	POST https://beta.digitzsapi.com/v3/generator/genPayment
Staging	POST https://api.staging.digitzs.com/v2/side-b/generator/genPayment

1

Authentication & Headers

Authorization: Bearer {{appToken}}
x-api-key: {{apiKey}}
Content-Type: application/json

2

Basic Request

The simplest request requires only your merchant ID and payment version:

{
    "merchant_id": "YOUR_MERCHANT_ID",
    "payment_version": "v4"
}

3

Example Implementation

async function generatePaymentForm() {
    // Use staging for testing, production for live transactions
    const endpoint = 'https://api.staging.digitzs.com/v2/side-b/generator/genPayment'; // Staging
    // const endpoint = 'https://beta.digitzsapi.com/v3/generator/genPayment'; // Production
    
    const response = await fetch(endpoint, {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer YOUR_APP_TOKEN',
            'x-api-key': 'YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "merchant_id": "YOUR_MERCHANT_ID",
            "payment_version": "v4"
        })
    });

    const result = await response.json();
    console.log('Generated form:', result);
    return result;
}

---

Configuration Parameters

Required Parameters

Parameter	Type	Description
merchant_id	string	Your unique merchant identifier
payment_version	string	Payment form version (use "v4" for latest features)

Parameter Details

Token vs Direct Payment

• enable_token: true - Returns a secure token for later processing (recommended)
• enable_token: false - Processes payment immediately upon form submission

Split Payments

• enable_split: true - Enables marketplace split payment functionality
• enable_split: false - Standard single-recipient payments

Field Collection

• is_capture_email: true - Shows email field (recommended for receipts)
• is_capture_zip: true - Shows ZIP code field (recommended for fraud prevention)

---

Custom Styling

You can customize the form appearance by providing CSS in the style parameter:

{
    "merchant_id": "YOUR_MERCHANT_ID",
    "payment_version": "v4",
    "style": "
        .payment-form { 
            background: #f8f9fa; 
            border-radius: 8px; 
            padding: 2rem; 
        }
        .submit-button { 
            background: #744ffe; 
            color: white; 
            border-radius: 6px; 
        }
    "
}

Want visual styling controls? For easier styling with a visual interface, use the Checkout Customizer instead.

---

API Response

Successful Response

{
    "message": "OK",
    "object_url": "https://digitz-iq-ui-iframe-content.s3.us-west-2.amazonaws.com/content-delivery/hppgdigitzs-paolomercha-718643500-3230807-1732171363.html",
    "shared_key": "K3qJJuAE7MJ2D-OEwda4t8UtuX4"
}

Response Fields

Field	Type	Description
message	string	Response status ("OK" for success)
object_url	string	Direct URL to the generated payment form
shared_key	string	Unique identifier for this form instance

---

Embedding the Generated Form

1

Basic Iframe Implementation

<iframe 
  src="GENERATED_OBJECT_URL" 
  width="100%" 
  height="600px" 
  frameborder="0"
  style="border: 1px solid #e3e8ee; border-radius: 8px;">
</iframe>

2

React Example

import React, { useEffect, useState } from 'react';

function PaymentForm() {
  const [formUrl, setFormUrl] = useState('');
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    fetch('/api/generate-payment-form')
      .then(response => response.json())
      .then(data => {
        setFormUrl(data.object_url);
        setLoading(false);
      })
      .catch(error => {
        console.error('Error generating form:', error);
        setLoading(false);
      });
  }, []);
  
  return (
    <div className="payment-container">
      <h1>Complete Your Payment</h1>
      {loading ? (
        <p>Loading payment form...</p>
      ) : (
        <iframe 
          src={formUrl}
          width="100%"
          height="600px"
          frameBorder="0"
          style={{border: '1px solid #e3e8ee', borderRadius: '8px'}}
        />
      )}
    </div>
  );
}

3

Dynamic Form Generation

async function createAndEmbedForm(formConfig) {
    try {
        const formData = await generatePaymentForm(formConfig);
        
        if (formData.message === 'OK') {
            const iframe = document.createElement('iframe');
            iframe.src = formData.object_url;
            iframe.width = '100%';
            iframe.height = '600px';
            iframe.frameBorder = '0';
            iframe.style.cssText = 'border: 1px solid #e3e8ee; border-radius: 8px;';
            
            const container = document.getElementById('payment-container');
            container.appendChild(iframe);
            
            sessionStorage.setItem('payment_shared_key', formData.shared_key);
        }
    } catch (error) {
        console.error('Form generation failed:', error);
    }
}

---

Advanced Configurations

Split Payment Setup

For marketplace scenarios where payments need to be split between multiple recipients:

{
    "merchant_id": "YOUR_MERCHANT_ID",
    "payment_version": "v4",
    "enable_split": true,
    "enable_token": true
}

Custom Branded Form

Create a fully branded payment experience:

{
    "merchant_id": "YOUR_MERCHANT_ID",
    "payment_version": "v4",
    "style": "
        body { font-family: 'Arial', sans-serif; }
        .form-container { 
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            border-radius: 12px;
            box-shadow: 0 10px 30px rgba(0,0,0,0.1);
        }
        .input-field { 
            border: 2px solid #744ffe;
            border-radius: 6px;
            padding: 12px;
        }
        .submit-btn { 
            background: #744ffe;
            color: white;
            padding: 14px 28px;
            border-radius: 8px;
            font-weight: 600;
        }
    "
}

---

Error Handling

Common Errors

Authentication Errors

{
    "error": "Unauthorized",
    "message": "Invalid app token or API key"
}

Solutions:

• Verify your appToken and apiKey are correct
• Ensure tokens haven't expired
• Check environment credentials

Invalid Merchant ID

{
    "error": "Invalid merchant",
    "message": "Merchant ID not found"
}

Solutions:

• Confirm your merchant_id is correct
• Ensure the merchant is active and verified

Parameter Validation

{
    "error": "Validation failed",
    "message": "Invalid payment_version"
}

Solutions:

• Use "v4" for the latest payment version
• Ensure boolean values are actual booleans, not strings

Error Handling in Code

async function generatePaymentForm(config) {
    try {
        const response = await fetch('https://beta.digitzsapi.com/v3/generator/genPayment', {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${config.appToken}`,
                'x-api-key': config.apiKey,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(config.formData)
        });

        if (!response.ok) {
            const errorData = await response.json();
            throw new Error(`API Error: ${errorData.message}`);
        }

        return await response.json();
    } catch (error) {
        console.error('Payment form generation failed:', error);
        throw error;
    }
}

---

Security Considerations

🔒 Security Best Practices:

• Always generate payment forms from your server
• Never expose API keys in client-side code
• Use HTTPS for all API calls and form embedding
• Validate all form generation requests

Secure Implementation Pattern

// Server-side endpoint (Node.js/Express example)
app.post('/api/generate-form', authenticateUser, async (req, res) => {
    try {
        const { amount, customerEmail } = req.body;
        
        if (!amount || !customerEmail) {
            return res.status(400).json({ error: 'Missing required fields' });
        }
        
        const formData = await generatePaymentForm({
            merchant_id: process.env.DEETS_MERCHANT_ID,
            payment_version: "v4",
            enable_token: true
        });
        
        res.json({ form_url: formData.object_url });
    } catch (error) {
        res.status(500).json({ error: 'Form generation failed' });
    }
});

---

When to Use Each Approach

Use Case	Visual Customizer	API Generation
One-time setup	✅ Recommended	❌ Overkill
Testing & prototyping	✅ Recommended	⚠️ Optional
Dynamic form generation	❌ Not suitable	✅ Recommended
Automated workflows	❌ Not suitable	✅ Recommended
Bulk operations	❌ Not suitable	✅ Recommended
Custom integrations	⚠️ Limited	✅ Recommended

---

Next Steps

Now that you've generated your payment form:

1. Listen for Events — Set up checkout event listeners to capture payment tokens
2. Process Payments — Use the captured tokens to create payments on your server
3. Test Integration — Validate your implementation with test transactions

---

Get Support

If you're unsure about a setting or something isn't working:

• Contact your technical team
• Reach out to Deets Support
• Check the API Reference for technical details