Gravity Forms VNPay Premium Add-on Setup Guide

The Gravity Forms VNPay Premium Add-on connects your Gravity Forms to your own VNPay merchant terminal, so customers in Vietnam can pay a form total in dong with VNPAY-QR, a domestic ATM card or bank account, or an international card. The customer pays on the VNPay payment page; card and bank details are entered there, never on your website. Before an entry changes, the add-on asks VNPay for the result with its transaction query and checks that it belongs to the entry. This guide covers every setting, the feed, the IPN address, refunds, sandbox testing and going live.

Installation

1. Upload the add-on zip in Plugins → Add New → Upload Plugin and activate it.
2. Open Forms → Settings → VNPay and activate your license key.
3. In Forms → Settings, set the currency to Vietnamese Dong. The add-on adds the dong to the Gravity Forms currency list (Gravity Forms does not have it).

The Vietnamese dong in Gravity Forms

VNPay takes payments in Vietnamese dong only. Gravity Forms has no dong of its own, so the add-on adds it to the currency list, only when no other plugin has added it already. Prices are shown as 1,250,000 ₫: no decimals, a comma between thousands and the dong sign on the right. The comma is on purpose. Gravity Forms reads any plain number before it looks at the currency format, so with dots between thousands a price typed as 150.000 would be read as 150 dong. With commas, every number reads the way it is written.

VNPay wants the amount multiplied by 100 (1,250,000 ₫ is sent as 125000000). The add-on does that for you from the total Gravity Forms calculated on your server, so the total the customer sees, the amount sent to VNPay and the amount on the entry are always the same.

Settings

When you save, the add-on checks the terminal code and hash secret with VNPay by asking for a transaction that does not exist. VNPay answers “not found” with a signature made with your secret, which proves both values are right; nothing is created or changed at VNPay. A pair VNPay refuses is not saved, and the connection line tells you so.

The IPN address

VNPay tells your site about each payment by calling an address on your site, the IPN (Instant Payment Notification) address. The settings page shows it, for example https://www.yourdomain.vn/?callback=gfvnpay. Send this address to VNPay technical support for your terminal, or enter it in the VNPay merchant portal where your account allows it. VNPay calls IPN addresses over https only.

Each IPN call is checked before anything else: the secure hash must match your hash secret, the terminal must be yours, the order reference must belong to an entry of this site and the amount must be the entry amount. Then the add-on asks VNPay again with its transaction query and only then updates the entry. The add-on answers VNPay in the format it expects: VNPay stops calling once the result is recorded and calls again, up to ten times every five minutes, if it could not be recorded yet.

The feed

In the form settings open VNPay and add a feed.

• Transaction type: Products and Services, or Donations. Subscriptions are not part of this add-on.
• Payment amount: usually the form total.
• Order description: sent to VNPay as the order information and shown in the VNPay merchant portal. Merge tags work, for example Thanh toan {form_title} {entry_id}. VNPay accepts Vietnamese without accents and without special characters, so the add-on removes accents (Đặt lớp becomes Dat lop) and turns other symbols into spaces.
• Payment method: leave the choice to the customer on the VNPay page (recommended), or open VNPAY-QR, domestic card and account, or international card directly.
• Goods category: the VNPay category code of what you sell. other fits most forms.
• Notifications: tick the option to send form notifications only after the customer has paid.

What the customer sees

The customer fills in the form and clicks your submit button (for example Continue to payment). The add-on builds a signed VNPay payment link on your server, with the total, a unique order reference, the order description, the payment page language and a signed return address, and sends the customer to the VNPay page. The page stays open for 15 minutes. There the customer scans the VNPAY-QR code with a banking app, or enters a domestic card or bank account, or an international card, and confirms.

When the customer comes back, they see your normal confirmation as soon as VNPay confirms the payment. If VNPay is still processing it, a short waiting message checks again by itself for about a minute, then tells the customer that the entry updates by itself. If the customer cancels on VNPay, they see that nothing was charged and a link back to the form.

Payment statuses

The entry screen

Every VNPay entry has a VNPay box on the right with the status, the amount, the order reference, the VNPay transaction number, the bank or method, the terminal, the reason when a payment did not go through, and any refunds. Sandbox payments carry a Sandbox badge.

• Refresh status asks VNPay for the payment again and applies it.
• Refund with VNPay sends a full or partial refund. Type the amount in dong (1250000 or 1,250,000 both work; the field starts with what can still be refunded) and confirm.

Refunds

Before a refund is sent, the add-on asks VNPay for the payment and checks that it was successful for the entry amount. A refund of the whole amount is sent as a full refund; anything less is sent as a partial refund, and you can make several partial refunds up to the amount paid. Each refund form can be used once, so a double click or a reloaded page cannot refund twice. VNPay’s signed answer is recorded once on the entry as a refund transaction; the entry becomes Refunded when the whole amount has been refunded.

If VNPay does not answer a refund request, the refund is kept as waiting and no second refund can be started. The status check asks VNPay for the payment; when VNPay shows it in refund, the refund is recorded. If VNPay still shows nothing an hour later, a note asks you to check the VNPay merchant portal before you refund again.

Testing in the sandbox

1. Register as a developer on VNPay’s sandbox site; VNPay emails a sandbox terminal code and hash secret.
2. Leave the mode on Sandbox and save the sandbox terminal code and hash secret. The connection line should say Connected to VNPay (Sandbox).
3. Give VNPay your IPN address for the sandbox terminal.
4. Open the form on your site, fill it in and continue to payment.
5. On the VNPay sandbox page, pay with the test card from VNPay’s sandbox documentation (the NCB test card and its OTP).
6. Back on your site, check the confirmation, then the entry: it should be Paid with the Sandbox badge, and the held notifications should have been sent.
7. Start another payment and press Cancel on the VNPay page: the entry becomes Cancelled.
8. Refund part of a paid test payment from the entry screen and watch it appear as a refund transaction.

Going live

1. When your VNPay merchant contract is active, VNPay sends the live terminal code, hash secret and live addresses.
2. Paste them into the Live fields and give VNPay your IPN address for the live terminal.
3. Switch the mode to Live and save. The connection line should say Connected to VNPay (Live).
4. Make one small real payment, check the entry and refund it from the entry screen.

Entries created in Sandbox keep asking the sandbox, and entries created in Live keep asking the live service, so test and real payments never mix.

For developers

• gravityextra_vnpay_payment_fields filters the payment fields before the link is signed. The order description, the goods category, the page language and the payment method can be changed; the amount, the order reference, the dates, the return address and the terminal cannot.
• gravityextra_vnpay_min_dong and gravityextra_vnpay_max_dong set the smallest and the largest payment the site accepts (defaults 5,000 ₫ and 9,999,999,999 ₫, the largest amount VNPay’s format allows; your VNPay terminal may have its own limits).
• gravityextra_vnpay_rate_limit changes the per-visitor limits (payment starts 10, return page 30, IPN calls 120 per minute).
• gravityextra_vnpay_payments_per_hour changes the site-wide cap of new payments per hour (300).
• gravityextra_vnpay_ipn_base changes the base of the IPN address (for a site behind a proxy).

// Put the class date in the VNPay order description for one form (ID 7)
// and open VNPAY-QR directly. Accents and symbols are removed for VNPay.
add_filter( 'gravityextra_vnpay_payment_fields', function ( $fields, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $fields;
    }
    $fields['vnp_OrderInfo'] = 'Lop gom ngay ' . rgar( $entry, '8' ) . ' ma ' . rgar( $entry, 'id' );
    $fields['vnp_BankCode']  = 'VNPAYQR';
    return $fields;
}, 10, 4 );

How it differs

• Card and bank details are entered on the VNPay page: the add-on only sends a signed payment link, so no card number, token or card form is ever on your site.
• Nothing decides a payment on its own: the return address and the IPN must carry VNPay’s secure hash, and even then the add-on asks VNPay again with its transaction query (whose answer is signed too) and checks the terminal, order reference and amount before the entry changes.
• The Vietnamese dong is added to Gravity Forms in a format that Gravity Forms reads correctly in the browser and on the server, and amounts are sent to VNPay multiplied by 100 exactly as VNPay asks, so totals never come out 100 times too big or too small.
• A repeated IPN never completes a payment twice, and VNPay gets the answer it expects, so it stops calling once the result is recorded.
• Terminal codes and hash secrets are checked with VNPay when you save and stored encrypted; live addresses must be on VNPay’s own hosts.
• Refunds from the entry screen are checked with VNPay first, protected by a one-time form, and kept as waiting when VNPay does not answer, so a refund is never sent twice.
• Payment creation, the return page and IPN calls have per-visitor limits, and new payments have an hourly cap, so a flood of form posts cannot create payments without end.

Troubleshooting

Uninstall

Uninstalling the add-on from Forms → Settings → Uninstall removes its settings (including the encrypted hash secrets), the status check schedule, the last-IPN marker, its locks, counters and cached checks. Entries, their notes and transactions stay, and nothing changes at VNPay.

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