How can we help you?

1. Overview & Business Value

The Gravity Forms Paymentwall Integration Add-on connects your WordPress forms directly to Paymentwall’s comprehensive multi-currency payment platform. By activating this integration, your store, donation form, or digital service can instantly accept payments across 200+ countries and territories through more than 150 local payment rails, including regional bank transfers (SEPA, Sofort, Giropay), digital e-wallets (Alipay, WeChat Pay, KakaoPay), prepaid options, and major credit/debit cards.

Unlike third-party middleware connectors (such as Zapier or Make) that introduce multi-minute webhook delays and per-transaction fees, this native integration handles payment processing and server-side pingbacks directly on your WordPress server with sub-second execution speeds and zero middleware overhead.

2. System Requirements & Prerequisites

Before installing and configuring the add-on, ensure your environment meets the following specifications:

• WordPress: Version 5.8 or higher.
• Gravity Forms: Version 2.5 or higher (Pro or Elite license recommended).
• PHP: Version 7.4, 8.0, 8.1, or 8.2 with cURL extension enabled.
• SSL Certificate (HTTPS): Required by Paymentwall to securely transmit payment tokens and pingbacks.
• Paymentwall Merchant Account: An approved project with active API credentials (Project Key and Secret Key).

3. Authentication & Global Configuration

To establish a secure API connection between Gravity Forms and Paymentwall, configure your credentials in the global settings:

1. Log into your WordPress Dashboard and navigate to Forms → Settings → Paymentwall.
2. Select your target environment: Test Mode for sandbox testing or Live Mode for production transactions.
3. Enter your Project Key (Application Key) copied from your Paymentwall Merchant Dashboard.
4. Enter your Secret Key.
5. Click Save Settings to validate the connection.

4. Merchant Dashboard & Pingback Webhook Setup

Paymentwall uses an asynchronous server-to-server callback called a Pingback to verify that a customer payment was completed successfully. Setting up this URL ensures that your form entries automatically update to "Paid" status.

1. Log into your Paymentwall Merchant Area and navigate to My Projects → Settings.
2. Locate the Pingback URL field and enter your site callback endpoint:
   
   https://yourdomain.com/?page=gf_paymentwall_ipn
3. Select Pingback Signature Version 2 or 3 for enhanced SHA-256 cryptographic security.
4. Set the HTTP pingback method to GET or POST as specified in your setup.
5. Click Save Changes in the Paymentwall dashboard.

5. Form Feed Configuration & Field Mapping

Each Gravity Form that processes payments through Paymentwall requires a dedicated form feed:

1. Open your form editor and navigate to Settings → Paymentwall.
2. Click Add New to create a new transaction feed.
3. Specify a Feed Name (e.g., "Global Product Checkout").
4. Select Transaction Type: Choose Products and Services for fixed/calculated item totals or Donations for variable amount contributions.
5. Map the Payment Amount to your form’s Total field or specific Product field.
6. Map Customer Billing Information: First Name, Last Name, Email, Address, and Country. Passing accurate customer location ensures Paymentwall displays the correct regional payment methods.
7. Click Save Settings.

6. Developer Extensibility & Action Hooks

Developers can customize the checkout parameters, currency overrides, or post-payment workflows using standard WordPress filters.

/**
 * Filter Paymentwall checkout parameters before user redirection
 *
 * @param array $params Checkout query arguments
 * @param array $form Current Gravity Form object
 * @param array $entry Current submitted entry
 * @return array Modified parameters
 */
add_filter( 'gform_paymentwall_args', function( $params, $form, $entry ) {
    // Dynamically override currency based on customer selection
    if ( ! empty( $entry['5'] ) ) {
        $params['currency'] = sanitize_text_field( $entry['5'] );
    }

    // Pass custom tracking identifier to Paymentwall
    $params['custom[user_id]'] = get_current_user_id();

    return $params;
}, 10, 3 );

7. Troubleshooting & Common Gotchas

Paymentwall Diagnostic Error Code & Resolution Matrix

Consult this diagnostic troubleshooting guide to resolve Paymentwall checkout, widget, or IPN pingback notification issues:

Frequently Asked Questions (FAQ)

Here are resolutions to the most frequent setup challenges:

• Pingback Not Updating Entry to "Paid": Security plugins (Wordfence, iThemes) or web application firewalls (Cloudflare) may block incoming POST requests to ?page=gf_paymentwall_ipn. Whitelist Paymentwall’s official IP ranges in your server firewall.
• "Invalid Signature" Error in Pingback Logs: Verify that the Secret Key configured in WordPress matches the exact Secret Key under your project in the Paymentwall dashboard. Also confirm the Pingback Signature version matches.
• Test Transactions in Live Mode: When testing, always use test card numbers and test payment rails provided by Paymentwall, and ensure Test Mode is toggled on in the add-on settings.
• Currency Mismatches: Ensure the currency configured in your Gravity Forms general settings matches an enabled currency in your Paymentwall merchant project.