How to Take VNPay Payments with Gravity Forms (VNPAY-QR, Cards, Vietnamese Dong)

VNPay is one of the most used payment gateways in Vietnam: customers scan a VNPAY-QR code with almost any banking app, or pay with a domestic ATM card, a bank account or an international card. If your class bookings, course fees, event tickets, deposits or donations already run on Gravity Forms, you do not need a full online shop to take those payments in dong. The Gravity Forms VNPay Premium Add-on connects your forms to your own VNPay merchant terminal. The customer pays on the VNPay page, and every entry shows the real result, confirmed with VNPay. This guide walks you through the whole setup, from the sandbox to your first real payment.

Why take VNPay payments through Gravity Forms?

A form is often the most natural way to sell something that is not a product on a shelf: a seat in a class, a consultation fee, an event pass, a course enrolment, a deposit for a custom order. Gravity Forms already handles the fields, the conditional logic and the total. What it needs is a safe way to collect the money in Vietnamese dong. With VNPay your customers pay the way they are used to, and with this add-on the money lands in your own VNPay merchant account.

• Customers pay on the VNPay page, never on your website.
• The amount is the total Gravity Forms calculated on your server, in whole dong.
• Entries show the real payment status, confirmed with VNPay, not what the browser says.
• Refunds are one click away on the entry screen.

Ways your customers can pay

By default the customer picks the method on the VNPay page. If most of your customers pay one way, the feed can open that method directly, for example VNPAY-QR for a class booked from a phone.

Forms that work well with VNPay

• Classes and workshops: seats, materials and options with quantities.
• Consultations and services: a fixed fee or a calculated amount for a booking.
• Schools and training centres: enrolments, course fees, exam and event registrations.
• Clubs, charities and associations: memberships, event passes and donations (choose Donations in the feed).
• Made-to-order products: options that change the price, paid before work starts.

What you need

• Gravity Forms 2.9 or newer, with the currency set to Vietnamese Dong (the add-on adds it to the list).
• A VNPay terminal: the sandbox terminal code and hash secret for testing (free developer registration on VNPay’s sandbox site), and the live ones once your merchant contract is active.
• The Gravity Forms VNPay Premium Add-on and a license: one site $49 a year, five sites $69 a year, unlimited sites $199 a year.
• A public site on https, so VNPay can call your IPN address.

Step 1: Install the add-on and connect your terminal

Upload and activate the add-on, then open Forms → Settings → VNPay and activate your license. Leave the mode on Sandbox and paste the sandbox terminal code (vnp_TmnCode) and hash secret (vnp_HashSecret) from the VNPay email. When you save, the add-on checks both with VNPay by asking for a transaction that does not exist, which changes nothing; the connection line then says Connected to VNPay (Sandbox), with the hash secret masked.

In Forms → Settings, set the currency to Vietnamese Dong. Gravity Forms does not have the dong, so the add-on adds it with prices like 1,250,000 ₫. It uses commas between thousands on purpose: Gravity Forms reads plain numbers before it applies the currency format, and with dots a price typed as 150.000 would turn into 150 dong.

Step 2: Give VNPay your IPN address

VNPay reports each payment by calling an address on your site, the IPN address, shown on the settings page (it ends in ?callback=gfvnpay). Send it to VNPay technical support for your terminal, or enter it in the VNPay merchant portal if your account allows it. Every call is checked with your hash secret, and the add-on then asks VNPay again before the entry changes, so a forged or repeated call changes nothing.

Step 3: Build the form

Build the form as you would for any payment: product fields with prices in dong and quantities, options, a total, and the customer’s name and email. Keep prices in whole dong. Change the submit button text to something like Continue to payment so customers know what comes next.

Step 4: Add a VNPay feed

In the form settings open VNPay and add a feed. Pick Products and Services (or Donations) and the form total as the amount. Write the order description that VNPay shows in your merchant portal; merge tags such as the form title and the entry number work, and accents are removed for you because VNPay accepts plain letters only. Choose whether the customer picks the payment method on VNPay, and tick the option to send form notifications only after payment.

Step 5: Test in the sandbox

Open the form on your site, fill it in and continue to payment. On the VNPay sandbox page, pay with the test card from VNPay’s sandbox documentation. You come back to your confirmation, and the entry shows Paid with a Sandbox badge. Try the other paths too: pressing Cancel on the VNPay page leaves the entry Cancelled, and a payment the bank refuses leaves it Failed. Then refund part of a test payment from the entry screen.

What happens behind the scenes

When the form is submitted, the add-on builds the VNPay payment link on your server: the total multiplied by 100 as VNPay asks, the dong as the currency, a unique order reference, the order description without accents, the time in Vietnam and an expiry 15 minutes later, the customer’s IP address, the page language and a signed return address. All of it is signed with your hash secret (HMAC-SHA512), so VNPay refuses a link that was changed on the way. No call to VNPay is needed to start a payment.

When the customer comes back, VNPay adds the result to the return address, and VNPay calls your IPN address with the same result. The add-on checks VNPay’s secure hash on both, then asks VNPay for the payment with its transaction query, whose answer is signed as well. The entry is marked Paid only when VNPay reports a successful payment for the entry’s terminal, order reference and amount. An address someone edited by hand, or a copied result from another payment, changes nothing.

A worked example

A pottery studio in Hội An sells three-hour classes at 1,250,000 ₫ and glaze sets at 99,000 ₫ through a Gravity Forms booking form. Hà books one class and one glaze set. Gravity Forms shows a total of 1,349,000 ₫; the add-on sends her to VNPay with an amount of 134900000 (the total times 100), the description “Thanh toan Dat lop lam gom 412” and a unique order reference. She scans the VNPAY-QR code with her banking app and confirms. Back on the studio’s site she sees the confirmation; behind the scenes the add-on has asked VNPay, which reported a successful payment of 1,349,000 ₫, and the entry is Paid with the VNPay transaction number. Two days later she can only come for half the materials, so the studio refunds 99,000 ₫ from the entry screen.

How it differs

• No card or bank details on your site: the customer pays on the VNPay page.
• Nothing is trusted from the browser or the IPN alone: VNPay’s secure hash is checked, then the payment is confirmed with VNPay’s transaction query and checked against the entry before it changes.
• The Vietnamese dong is added to Gravity Forms in a format Gravity Forms reads correctly, and the amount is sent to VNPay multiplied by 100 exactly as VNPay asks.
• A repeated IPN never completes a payment twice, and VNPay gets the answer it expects.
• Terminal codes and hash secrets are checked with VNPay when you save and stored encrypted, and every entry keeps the mode (sandbox or live) it was created in.
• Full and partial refunds are checked with VNPay first and protected by a one-time form.
• Per-visitor limits and an hourly cap stop a flood of form posts from creating payments without end.

Tips for smooth payments

• Keep every price in whole dong, so the total is always a whole number of dong.
• Put the entry number in the order description, so you can find the entry from a transaction in the VNPay merchant portal.
• Hold form notifications until payment so your team only sees paid bookings.
• Use the Payment Completed notification event to send the customer a receipt from your site.
• Make sure VNPay has your IPN address for both the sandbox and the live terminal, so entries update the moment a payment is made.
• For bookings made mostly from phones, try opening VNPAY-QR directly from the feed.

Step 6: Go live

When your VNPay merchant contract is active, VNPay sends the live terminal code, hash secret and the live payment and API addresses. Paste them into the Live fields, give VNPay your IPN address for the live terminal, switch the mode to Live and save. Make one small real payment, check the entry, and refund it from the entry screen. Entries created in Sandbox keep asking the sandbox, so nothing mixes.

Questions

Do card or bank details reach my website?

No. The customer pays on the VNPay page. Your site only receives the result: the order reference, the amount, the VNPay transaction number, the bank and the status.

Can I take payments in US dollars?

No. VNPay takes payments in Vietnamese dong, so the form currency must be the dong. Forms in another currency are refused before the customer leaves the form.

What if the IPN never arrives?

The return page asks VNPay when the customer comes back, the status check asks VNPay for waiting payments every five minutes, and you can click Refresh status on the entry at any time.

Can I refund part of a payment?

Yes. Type the amount on the entry screen. You can make several partial refunds up to the amount paid; the entry becomes Refunded when the whole amount has been refunded.

Are subscriptions or instalments supported?

This add-on handles one-off payments: products, services and donations.

Get started

Read the setup guide for every setting, or get the Gravity Forms VNPay Premium Add-on and take your first VNPay payment through Gravity Forms today. Plans: one site $49 a year, five sites $69 a year, unlimited sites $199 a year.