How can we help you?

1. Overview & Paddle Billing v2 Architecture

The Gravity Forms Paddle Integration Add-on connects Gravity Forms with Paddle Billing v2, the premier Merchant of Record (MoR) platform designed specifically for software, SaaS, and B2B digital commerce.

Operating as your Merchant of Record, Paddle takes on full global tax compliance, local entity registration, foreign exchange conversion, invoicing, and PCI compliance in over 200 territories. This allows software founders and web agencies to sell worldwide without managing individual VAT/GST tax registrations.

Paddle Billing v2 Architecture & Merchant of Record Mechanics

Paddle Billing v2 represents the next evolution of global digital sales infrastructure. As your Merchant of Record, Paddle acts as the legal reseller of your software and services, providing an end-to-end framework that shields your agency or SaaS from regulatory friction:

• Comprehensive Tax Remittance: Collects, files, and remits indirect taxes across over 200 sovereign jurisdictions, including EU VAT, UK VAT, Australian GST, Canadian HST/PST, and US state sales taxes.
• B2B Invoicing & Reverse Charge: Automatically validates enterprise VAT IDs via the European VIES database in real time, issuing compliant B2B reverse charge invoices with 0% tax.
• Multi-Currency Settlement: Customers pay in their local currency (EUR, GBP, USD, JPY, AUD, etc.) while Paddle settles earnings into your domestic bank account in your preferred payout denomination.
• Chargeback Protection: Paddle manages banking dispute representations and absorbs processing risks, shielding your business from punitive gateway monitoring programs.

In-Context Overlay vs Hosted Checkout Portals

The Gravity Forms Paddle integration supports two distinct checkout presentation modes to suit your branding and conversion requirements:

• Paddle.js Inline Overlay: A sleek, responsive modal opens directly on top of your Gravity Forms page. The customer completes payment without leaving your site, maximizing form completion rates.
• Hosted Checkout Redirection: For enterprise B2B purchasing or clients requiring dedicated full-page checkout environments, the add-on seamlessly redirects customers to Paddle’s ultra-secure hosted payment domain and returns them to your custom confirmation URL upon completion.

2. Paddle Billing Setup & API Authentication

To authenticate Gravity Forms with Paddle Billing v2:

1. Log in to your Paddle Dashboard.
2. Navigate to Developer Tools → Authentication.
3. Generate a new API Secret Key. Ensure it has permissions for Transactions and Subscriptions.
4. Under Developer Tools → Notifications, create a new webhook endpoint pointing to your site URL: https://yourdomain.com/?callback=gfpaddleaddon. Copy your Notification Secret Key.
5. In WordPress, navigate to Forms → Settings → Paddle.
6. Select your operational Environment (Sandbox for staging or Production for live billing).
7. Enter your API Secret Key and Webhook Secret, then click Save Settings.

3. Feed Configuration & Price ID Mapping

Create payment feeds that link Gravity Forms submissions to Paddle transactions:

1. Inside the Gravity Forms editor, go to Settings → Paddle and click Add New.
2. Set a Feed Name (e.g. Enterprise License Checkout).
3. Price ID / Product Catalog: Enter your Paddle Price ID (e.g. pri_01h...) or select dynamic form total calculation.
4. Customer Details: Map customer Name, Email, and Business Country. Paddle applies localized pricing and tax automatically based on the customer’s verified country.
5. Checkout Experience: Choose between an inline overlay checkout or a clean redirect to Paddle’s hosted checkout portal.

4. Advanced B2B & SaaS Workflows

Power your B2B subscription and invoicing workflows with Paddle:

• EU VAT Reverse Charge: Paddle automatically validates European VAT numbers at checkout. If a company enters a valid VAT ID, Paddle applies the 0% reverse charge mechanism automatically.
• Automated B2B PDF Invoicing: Paddle generates compliant PDF invoices with official company tax numbers for corporate accounting.
• Subscription Webhooks: Background webhooks update entry payment status on recurring renewals and automatically trigger notification emails.

Paddle Sandbox Testing & Simulation Protocol

Before accepting real customer payments, thoroughly test your checkout feeds in the Paddle Sandbox environment. Paddle provides dedicated test credit card numbers, simulate successful authorizations, card declines, and 3D Secure bank verification challenges. You can also simulate subscription lifecycle webhook events directly from the Paddle Developer Notifications dashboard to verify that your WordPress entry notes and notifications update correctly.

5. Troubleshooting & Error Code Matrix

6. Developer Extensibility & Filter Hooks

Filter Paddle checkout transactions dynamically:

/**
 * Customize Paddle Billing transaction payload
 *
 * @param array $payload Transaction creation structure
 * @param array $feed Current feed settings
 * @param array $entry Current entry
 * @return array
 */
add_filter( 'ge_paddle_transaction_payload', function( $payload, $feed, $entry ) {
    // Inject internal metadata for accounting sync
    $payload['custom_data'] = [
        'gravityforms_entry_id' => $entry['id'],
        'organization_id'       => get_user_meta( get_current_user_id(), 'org_id', true ),
    ];

    return $payload;
}, 10, 3 );

7. Frequently Asked Questions (FAQ)

Q: Does Paddle handle customer sales tax and invoices?

Yes. As a Merchant of Record, Paddle acts as the seller of record, generating localized VAT invoices and handling tax compliance in 200+ countries.

Q: Does this work with Paddle Billing v2?

Yes. The add-on is built on Paddle’s modern Billing v2 APIs, supporting granular subscriptions, flexible billing cycles, and automated webhook notifications.

Q: Can I offer free trials with credit card upfront?

Yes. In your Paddle Billing price configuration, you can specify a trial period (e.g. 14 days). Paddle securely tokenizes the payment method upon form submission and only charges the card once the trial concludes.

Q: How does Paddle handle subscription upgrades or downgrades?

Paddle automatically manages proration calculations when customers change plans. Webhook notifications notify your WordPress site of plan adjustments so you can update entry metadata and user capabilities accordingly.