Gravity Forms PhonePe Premium Add-on Setup Guide

The Gravity Forms PhonePe Premium Add-on lets your Gravity Forms take payments in Indian rupees through PhonePe PG, the PhonePe payment gateway. When a form is submitted, the add-on creates a PhonePe order for the exact total and sends the customer to the PhonePe payment page, where they pay by UPI, card or net banking. When they come back, or when PhonePe sends its webhook, the add-on reads the order back from PhonePe and only then marks the entry as paid. Refunds, full or partial, are made from the entry screen. This guide covers every setting, the feed, what happens during a payment, refunds, testing in the UAT sandbox and going live.

How a payment works

1. The customer fills in the form. Gravity Forms works out the total; the add-on checks that it is a rupee amount with at most two decimals and at least 1.00 INR.
2. The entry is saved with the status Processing. The add-on asks PhonePe for an access token with your credentials (it is kept, encrypted, until shortly before it expires) and creates a Standard Checkout order on your server: the total in paise, a unique order reference, the reference again in the order details, a short message, a signed return link and, when you map it, the customer’s mobile number to fill in the PhonePe login.
3. PhonePe answers with the order and its payment page. Before the customer is sent there, the add-on checks that the order is open (PENDING) and that the page is on phonepe.com. If anything differs, the customer is told that nothing was charged and the entry is marked Failed.
4. The customer pays on the PhonePe page by UPI (an app, a QR code or a UPI ID), by card or by net banking. Payment details are entered on PhonePe and never reach your website.
5. PhonePe sends the customer back to your form page and posts a webhook to your site. Either way, the add-on reads the order from PhonePe and updates the entry: Paid, Failed or Cancelled.
6. Orders are open for twenty minutes. An order that is never paid ends as Failed or Cancelled when PhonePe reports it, and no money is taken.

Install and activate

1. In WordPress go to Plugins → Add New → Upload Plugin, upload the zip and activate it.
2. Open Forms → Settings → PhonePe, enter your GravityExtra license key and activate it. The settings below appear once the license is active.
3. Check Forms → Settings: the currency must be Indian Rupee.

Settings

Open Forms → Settings → PhonePe. Both modes have their own credentials; only the credentials of the mode you choose are used for new orders. An entry always keeps the mode it was created in, so an order started in Test mode is still read from the UAT sandbox after you switch to Live.

Getting your credentials

1. Sign in to the PhonePe Business Dashboard and open Developer Settings.
2. Copy the Client ID, the Client Version and the Client Secret of the UAT (test) environment into the Test fields, then save. The connection line turns green when PhonePe accepts them.
3. When PhonePe has activated your account for production, copy the production credentials into the Live fields.

Setting up the webhook

1. Copy the webhook address shown on the settings page. It is your site address with ?callback=gfphonepe.
2. In the PhonePe dashboard, add a webhook with this address, choose a username and a password, and select the order events (completed and failed) and the refund events (completed and failed).
3. Enter the same username and password in the add-on settings and save. PhonePe signs each webhook with a SHA256 hash of them; a webhook without the right hash is refused.

The feed

Open your form, go to Settings → PhonePe and add a feed. Choose Products and Services or Donations and the payment amount (usually the form total). Then map the customer fields: the mobile number fills in the PhonePe login so the customer can pay faster (an Indian mobile number typed as +91 98765 43210, 098765 43210 or 9876543210 is sent as ten digits; other numbers are left out), and the email is checked and kept with the entry.

• Payment message: sent with the PhonePe order, up to 60 characters. Merge tags work; the default is the form title and the entry number.
• Notifications: tick Send form notifications only after the customer has paid to hold the usual form notifications until the payment is confirmed. They are sent once, when the entry becomes Paid.
• Payment events: in the form notifications you can also choose Payment Completed, Payment Failed or Cancelled and Payment Refunded as the event.

The form and the PhonePe page

Use Gravity Forms product, quantity, option and total fields as usual. The amount sent to PhonePe is the total Gravity Forms calculated on your server, in paise, so a total changed in the browser cannot lower the price. The submit button can say Continue to payment, because the customer goes to the PhonePe page next.

When the customer comes back, they see your normal confirmation if the payment is complete. If PhonePe has not confirmed it yet (a UPI payment can take a few seconds), a short waiting message checks again by itself every few seconds. If the payment failed or was cancelled, the customer is told that nothing was charged and can return to the form.

Payment statuses

The entry screen

Every PhonePe entry has a PhonePe box on the right with the status, the amount, the PhonePe order id, the order reference, the payment mode, the PhonePe transaction id, the error code if there was one, and the refunded total and any refund still in progress. Test payments carry a Test badge.

• Refresh status reads the order and any pending refund from PhonePe again and applies them.
• Refund with PhonePe sends a full or partial refund to the customer. Type the amount in rupees (the field starts with the amount left) and confirm.

Refunds

Before a refund is sent, the add-on reads the order from PhonePe and checks that it is complete for the entry amount, and that the refund fits what is left after earlier and pending refunds (from 1.00 INR). Each refund form can be used once, so a double click or a reloaded page cannot refund twice. PhonePe processes refunds in the background: the amount is reserved at once, and the refund is recorded on the entry as a transaction with a note when PhonePe completes it (by the refund webhook, the status check or Refresh status). If PhonePe reports the refund as failed, the amount is free again. When the whole amount has been refunded the entry becomes Refunded. Refunds you make in the PhonePe dashboard are recorded too, when PhonePe sends the refund webhook.

Testing in the UAT sandbox

1. Leave the mode on Test and save your UAT credentials and the webhook username and password.
2. Open the form on your site, fill it in and continue to payment.
3. On the PhonePe page, pay with the test cards or the UPI test flows from the PhonePe UAT documentation (the bank page accepts the test OTP given there). The failure and pending test flows let you check the other paths.
4. Back on your site, check the confirmation, then the entry: it should be Paid with the Test badge, and the held notifications should have been sent.
5. Try a partial refund from the entry screen and watch it move from in progress to completed.
6. Start another payment and leave the PhonePe page without paying: the entry should end as Failed or Cancelled once PhonePe reports the order.

Going live

1. Complete the PhonePe PG onboarding so PhonePe activates your account for production payments.
2. Copy the production Client ID, Client Version and Client Secret into the Live fields, and set up the production webhook with the same address, username and password.
3. Switch the mode to Live and save. The connection line should say Connected to PhonePe (Live, production).
4. Make one small real payment, check the entry and refund it from the entry screen.

For developers

• gravityextra_phonepe_order_fields filters the order before it is sent (for example to add udf2 to udf10 details). The amount, the order reference, the flow type, the return link and udf1 cannot be changed by it; unknown keys are dropped.
• gravityextra_phonepe_max_paise changes the largest order the site accepts (10,00,000 INR, in paise).
• gravityextra_phonepe_rate_limit changes the per-visitor limits (payment starts 10, return page 30, webhooks 120 per minute).
• gravityextra_phonepe_payments_per_hour changes the site-wide cap of new orders per hour (300).
• gravityextra_phonepe_webhook_base changes the base address of the webhook (for a site behind a proxy).

// Keep the class date with the PhonePe order (udf2..udf10 are free) for one form (ID 7).
add_filter( 'gravityextra_phonepe_order_fields', function ( $order, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $order;
    }
    $order['metaInfo']['udf4'] = rgar( $entry, '8' );
    return $order;
}, 10, 4 );

How it differs

• Nothing is trusted from the browser or the webhook body: every result is read back from PhonePe and checked against the entry’s order reference, PhonePe order id and amount before the entry changes.
• Webhooks must carry the hash of your webhook username and password; a webhook without it is refused, and a repeated webhook is dropped, so a payment can only be completed once.
• Credentials are checked with PhonePe when you save, the access token is kept encrypted and renewed by itself, and each entry stays with the mode it was created in.
• Refunds from the entry screen are checked against PhonePe first, protected by a one-time form, reserved while PhonePe processes them and followed until they complete; dashboard refunds are recorded too.
• Payment creation, the return page and webhooks have per-visitor limits, and new orders have an hourly cap, so a flood of form posts cannot create orders without end.
• It uses the current PhonePe PG Standard Checkout API (access token and order status), not the older salt-key checksum flow.

Troubleshooting

Uninstall

Uninstalling the add-on from Forms → Settings → Uninstall removes its settings (including the encrypted secrets), the status check schedule, its locks, counters, cached tokens and checks. Entries, their notes and transactions stay in Gravity Forms, and orders and refunds at PhonePe are not touched.

Plans: one site $49 a year, five sites $69 a year, unlimited sites $199 a year. Questions? Contact GravityExtra support.