FF

FIRAFORM

Docs

Comprehensive guides and references for FiraForm.

Payment Integration

Accept payments through your forms with PayPal, Stripe, SecurePay, BillPlz, Bayarcash, or Chip

Payments

FiraForm lets you accept payments directly through your forms. Set up a payment gateway at the team level, enable it on individual forms, and let your visitors pay during form submission.

How It Works

Payment integration works in two layers:

  1. Team level — Connect your payment gateway credentials (PayPal, Stripe, etc.) once per team. These credentials are shared across all forms in that team.
  2. Form level — Enable the payment gateway on each form that needs to collect payments, and configure form-specific settings like amount and currency.

When a visitor submits the form, they are redirected to the payment gateway to complete the transaction. After payment, they are redirected back to your site, and FiraForm waits for the gateway’s server-to-server webhook to confirm the payment before sending notifications.

Supported Gateways

GatewaySandboxLiveNotes
PayPal✅✅Redirects to PayPal checkout page
Stripe✅✅Stripe Checkout redirect
SecurePay✅✅Malaysian payment gateway
BillPlz✅✅Malaysian billing platform
Bayarcash✅✅Malaysian payment gateway
Chip✅✅Malaysian payment gateway

Step 1: Set Up Team Payment Gateway

  1. Go to Team → Integrations
  2. Select your payment provider
  3. Choose an environment:
    • Sandbox — For testing. Use test credentials from your gateway’s developer dashboard.
    • Live — For real transactions. Use production credentials.
  4. Enter the required credentials (varies by provider):
    • PayPal: Client ID, Client Secret, Webhook ID, Default Currency
    • Stripe: Secret Key, Webhook Signing Secret, Default Currency
    • SecurePay: API UID, Auth Token, Checksum Token
    • BillPlz: API Key, Collection ID, X-Signature Key
    • Bayarcash: Portal Key, Personal Access Token, API Secret Key, Payment Channel
    • Chip: API Key, Brand ID, Public Key
  5. Click Save

Important: You must be a team Owner or Admin to manage payment integrations.

Step 2: Enable Payment on a Form

  1. Go to your form’s Integrations tab
  2. Find the payment provider you set up at the team level
  3. Click to enable it
  4. Configure form-level settings (see below)

Note: The team-level credentials must be configured first. You cannot enable a form-level integration if the team credentials are missing.

Form Payment Settings

  • Amount Source — How the payment amount is determined:
    • Fixed Amount — Enter a fixed amount in the form settings
    • From Field — Read the amount from a form field (default: _ff_amount)
  • Currency — The currency code (e.g., USD, MYR, EUR). Falls back to the team-level default currency if not set.
  • Payer Email Field — The form field that contains the payer’s email (default: _ff_buyer_email)
  • Payer Name Field — The form field that contains the payer’s name (default: _ff_buyer_name)
  • Success Redirect URL — Where to send the visitor after successful payment. Set this in the Form Settings tab, not in the HTML form (optional, paid plans only).
  • Cancel Redirect URL — Where to send the visitor if they cancel payment. Set this in the Form Settings tab, not in the HTML form (optional, paid plans only).

Note: These redirect URLs cannot be passed via form input fields. They must be configured in the Form Settings UI. Free plan users cannot configure redirect URLs — FiraForm will display its own default success and cancel pages. Paid users who leave these blank will also see FiraForm’s default pages.

Step 3: Add Payment Fields to Your Form

Add these special fields to your HTML form so FiraForm can process the payment:

Required Fields

FieldDescription
_ff_amountThe payment amount (e.g., 19.99). Must be a positive number.

Optional Fields

FieldDescription
_ff_currencyCurrency code (e.g., USD, MYR). Falls back to team default.
_ff_payment_gatewaySpecify which gateway to use when multiple are enabled (e.g., stripe).
_ff_buyer_namePayer’s name. Used by SecurePay, Bayarcash, BillPlz, and Chip.
_ff_buyer_emailPayer’s email. Used by SecurePay, Bayarcash, BillPlz, and Chip.
_ff_buyer_phonePayer’s phone number. Used by SecurePay, Bayarcash, and Chip.

Example: Simple Payment Form

<form action="https://a.firaform.com/api/f/YOUR-FORM-UUID" method="POST">
    <input type="text" name="name" placeholder="Your Name" required>
    <input type="email" name="email" placeholder="Email" required>

    <!-- Payment fields -->
    <input type="hidden" name="_ff_amount" value="29.99">
    <input type="hidden" name="_ff_currency" value="USD">
    <input type="hidden" name="_ff_buyer_name" value="">
    <input type="hidden" name="_ff_buyer_email" value="">

    <button type="submit">Pay Now</button>
</form>

<script>
    // Populate buyer fields from visible form inputs before submission
    document.querySelector('form').addEventListener('submit', function() {
        this.querySelector('[name="_ff_buyer_name"]').value = this.querySelector('[name="name"]').value;
        this.querySelector('[name="_ff_buyer_email"]').value = this.querySelector('[name="email"]').value;
    });
</script>

Example: Variable Amount (User Chooses)

<form action="https://a.firaform.com/api/f/YOUR-FORM-UUID" method="POST">
    <input type="email" name="email" placeholder="Email" required>

    <label>Choose amount:</label>
    <select name="_ff_amount">
        <option value="9.99">Basic - $9.99</option>
        <option value="19.99">Pro - $19.99</option>
        <option value="49.99">Business - $49.99</option>
    </select>

    <input type="hidden" name="_ff_currency" value="USD">

    <button type="submit">Pay Now</button>
</form>

Example: Multiple Gateways

When you have multiple gateways enabled on a form, visitors are shown a gateway selection page. You can skip this by setting _ff_payment_gateway:

<input type="hidden" name="_ff_payment_gateway" value="stripe">

Important: All _ff_* fields are stripped from the saved submission data. They are used only for payment processing and never appear in your submissions or metadata.

Securing the Amount Field

The _ff_amount field is submitted as a regular form input, which means a technically savvy visitor could modify it. To protect against this, add validation rules in the Form Fields tab:

  1. Go to Form → Fields
  2. Click Add Field
  3. Enter field name: _ff_amount
  4. Set type to Number
  5. Set Min Value and Max Value to constrain the allowed range
  6. Mark as Required
  7. Click Save Rules

This ensures submissions with missing, zero, negative, or out-of-range amounts are rejected before payment processing begins.

The _ff_amount field can be any HTML input type — a text field, a dropdown, radio buttons, or a hidden field. For example, if the amount depends on user selection, you can use radio buttons:

<input type="radio" name="_ff_amount" value="9.99"> Basic - $9.99
<input type="radio" name="_ff_amount" value="19.99"> Pro - $19.99
<input type="radio" name="_ff_amount" value="49.99"> Business - $49.99

If the amount is set dynamically by JavaScript based on user interaction, use a hidden field and populate it on form submit:

<input type="hidden" name="_ff_amount" id="_ff_amount">

<script>
document.querySelector('form').addEventListener('submit', function() {
    document.getElementById('_ff_amount').value = calculateAmount();
});
</script>

Auto-Reply Emails After Payment

When payment is enabled on a form, auto-reply emails (and all other notifications) are deferred until the payment is confirmed. This means:

  • The visitor submits the form and is redirected to the payment gateway
  • If they complete payment, the webhook confirms it and FiraForm sends the auto-reply email
  • If they cancel or the payment fails, no auto-reply is sent

Setting Up Auto-Reply for Payment Forms

  1. Go to Form → Settings → Auto Reply
  2. Enable auto-reply
  3. Set the Email Field to the field containing the payer’s email (e.g., email or _ff_buyer_email)
  4. Compose your subject and body
  5. Use {{field_name}} placeholders to personalize the email

Example auto-reply body:

Hi {{name}},

Your payment of ${{_ff_amount}} has been received. Thank you!

We'll process your order shortly.

- The Team

Note: The _ff_* fields are available as placeholders in auto-reply emails, so you can include the payment amount, currency, or any other payment data in your confirmation email.

How Payment Processing Works

Here is the full flow from submission to notification:

  1. Visitor submits form → FiraForm saves the submission
  2. Payment check → FiraForm checks if payment gateways are enabled on the form
  3. Amount check → If _ff_amount is missing or invalid, payment is skipped and notifications are sent immediately
  4. Gateway selection → If multiple gateways are enabled and no _ff_payment_gateway is specified, the visitor sees a selection page
  5. Redirect to gateway → The visitor is redirected to the external payment page (PayPal, Stripe, etc.)
  6. Visitor completes payment → The gateway processes the payment
  7. Return redirect → The visitor is redirected back to your site (success or cancel page)
  8. Webhook confirmation → The gateway sends a server-to-server webhook to FiraForm to confirm the payment status
  9. Notifications sent → On success, FiraForm dispatches auto-reply emails, notification emails, webhooks, and other integrations

Important: Notifications (including auto-reply emails) are only sent after the webhook confirms payment. The return redirect page that the visitor sees is separate from the server-side confirmation.

Webhook URLs

Each gateway has a unique webhook URL. You can find your team’s webhook URL in the Integrations settings. The format is:

https://a.firaform.com/payments/{gateway}/webhook/{your-team-webhook-token}

Note: FiraForm automatically verifies the webhook signature for each gateway to ensure authenticity. Do not share your webhook token publicly.

Tips

  • Start with sandbox: Always test with sandbox credentials before going live
  • Validate amounts: Add field validation rules for _ff_amount to prevent tampering
  • Use auto-reply: Send a confirmation email after payment succeeds so customers know their payment went through
  • Test the full flow: Submit a test form, complete payment on the sandbox gateway, and verify that the webhook fires and notifications are sent
  • Check webhook delivery: Monitor your gateway’s webhook logs to confirm deliveries are reaching FiraForm
  • Custom redirects (paid): Paid users can set success/cancel redirect URLs in the form’s payment settings for a branded experience. Free plans use FiraForm’s default pages.
  • Amount is required: If _ff_amount is missing from the submission, payment is silently skipped — the form submission still saves and notifications still send, just without payment