Understanding FillFaster Form Payments

The Payment Feature allows you to integrate payment processing directly into your forms. Users can make payments through a secure checkout process without leaving your form, and the payment status is automatically tracked and validated.

Key Features

• Secure Payment Processing: Payments are processed through external payment gateways in secure iframes
• Form Integration: Payment status is integrated with form validation - required payments must succeed before form submission
• Dynamic Configuration: Payment settings can be configured statically in the form schema or dynamically via submission data
• Multiple Payment Fields: Support for multiple payment fields within a single form

How It Works

1. Payment Button: When payment criteria are met, a payment button is displayed
2. Dynamic URL Generation: Clicking the button calls the backend API to generate a unique checkout URL
3. Secure Checkout: The checkout page opens in a popup iframe where users enter payment details
4. Status Detection: The system monitors iframe URL changes to detect payment completion
5. Form Validation: Payment status is integrated with form validation - failed required payments prevent form submission

Supported gateways

Form payments are integrated with external gateways. Currently supported:

Gateway	gateway value (schema / config)
EasyCard	easycard

Additional gateways may be added over time. check this page or FillFaster’s release notes when planning new payment flows.

Configuration Options

Static Configuration (Form Schema)

Payment fields can be configured directly in the form schema with predefined settings:

{
  "type": "payment",
  "key": "processing_fee",
  "label": "Processing Fee",
  "required": true,
  "validationType": "payment",
  "paymentType": "paymentIntent",
  "gateway": "easycard",
  "payload": {
    "currency": "ILS",
    "paymentRequestAmount": 10,
    "paymentIntent": true
    ..easycard paymentIntent regular payload
  }
}

Dynamic Configuration (Submission Data)

For more flexible payment processing, payment configurations can be provided dynamically in the submission data under the payment_configs section:

{
  "form_id": "abc123",
  "inputs": {
    "user_name": "John Doe",
    "user_email": "john@example.com",
    "user_phone": "0501234567"
  },
  ...
  "payment_configs": {
    "field_name": {
      "paymentType": "paymentIntent",
      "gateway": "easycard",
     "payload": {
    "currency": "ILS",
    "paymentRequestAmount": 10,
    "paymentIntent": true
        .. easycard paymentIntent regular payload
      }
    }
  }
}

Hybrid Configuration

The system supports a hybrid approach where:

1. Dynamic configurations (from payment_configs) take precedence
2. Static configurations (from schema) serve as fallback defaults
3. This allows for both simple predefined payments and complex dynamic payment flows

Field Configuration Properties

Required Properties

• type: Must be "payment"
• key: Unique identifier for the payment field
• label: Display name for the payment field
• validationType: Must be "payment"

Optional Properties

• required: Whether the payment is required for form submission (default: false)
• paymentType: Type of payment (e.g., "paymentIntent")
• gateway: Payment gateway to use (e.g., "easycard")
• payload: Payment configuration object

Payment Status Values

The payment field can have the following status values:

• "pending": Initial state, payment not yet attempted
• "success": Payment completed successfully
• "failed": Payment failed or was cancelled
• "missing_config": Payment configuration is missing (automatically set when required payment has no configuration)

Examples

Example 1: Simple Required Payment

Schema Configuration:

{
  "type": "payment",
  "key": "registration_fee",
  "label": "Registration Fee",
  "required": true,
  "validationType": "payment",
  "paymentType": "paymentIntent",
  "gateway": "easycard",
  "payload": {
    "currency": "ILS",
    "paymentRequestAmount": 10,
    "paymentIntent": true
        .. easycard paymentIntent regular payload
     }
  }
}

Dynamic Configuration (overrides schema), sent under payment_configs in createSubmission link request: Documentation Link

Example 2: Dynamic Payment with Placeholders

Dynamic Placeholder:

A text with {service_payment} placeholder

Dynamic Configuration (overrides schema), sent under payment_configs in createSubmission link request: Documentation Link

{
  "form_id": "abc123",
  "inputs": {
    "user_name": "John Doe",
    "user_email": "john@example.com",
    "user_phone": "0501234567"
  },
  ...
  "payment_configs": {
    "service_payment": {
      "paymentType": "paymentIntent",
      "gateway": "easycard",
      "payload": {
    "currency": "ILS",
    "paymentRequestAmount": 10,
    "paymentIntent": true
        .. easycard paymentIntent regular payload
        }
      }
    }
  }

Security Considerations

• Secure Communication: Payment URLs are generated server-side
• Iframe Security: Checkout pages are loaded in sandboxed iframes

Troubleshooting

Common Issues

1. Payment button not showing: Check that all required configuration properties are present
2. Payment URL generation fails: Verify the payload is aligned with the payment provider documentation.
3. Form submission allowed despite failed payment: Ensure payment field is marked as required: true, the default value is true.