Gravity Forms MoMo Premium Add-on Setup Guide

The Gravity Forms MoMo Premium Add-on connects Gravity Forms to your own MoMo business account in Vietnam. When a form with a MoMo feed is submitted, the add-on creates a MoMo payment for the exact total Gravity Forms calculated, in Vietnamese dong, and sends the customer to the MoMo payment page. On a computer the customer scans the QR code with the MoMo app; on a phone the MoMo app opens directly. Payment details stay in the MoMo app, never on your website.

When MoMo reports the payment, the add-on checks the signature of the notification with your secret key, reads the payment back from MoMo and only then marks the entry Paid, with the MoMo transaction ID as the transaction ID. This guide covers installation, the currency, every setting, payment notifications, the feed, what the customer sees, the payment statuses, refunds, testing with the MoMo test environment and going live.

Installation

1. Download the add-on zip from your GravityExtra account and upload it in Plugins → Add New → Upload Plugin, then activate it.
2. Open Forms → Settings → MoMo and activate your licence key. The MoMo settings appear once the licence is active.
3. In Forms → Settings, set the Gravity Forms currency to Vietnamese Dong (VND). The add-on adds it to the list.

Currency and amounts

Gravity Forms does not include the Vietnamese dong out of the box. The add-on adds it to the Gravity Forms currency list as soon as it is active, written the way your customers expect: 1,250,000 ₫, with comma thousands and no decimals. It never changes a dong definition that another plugin already made.

The amount is worked out on your server from the entry, never from the browser. A total that is not a whole number of dong, below 1,000 VND or above 50,000,000 VND is refused before anything is sent, so the customer is never charged a rounded amount. Comma thousands are deliberate: Gravity Forms reads a plain number such as 150000 as written, while a dot-thousands format could turn a typed “150.000” into 150 dong.

Settings

Payment notifications

MoMo tells your site about a payment by posting the result to a notification address (IPN). The add-on sends its own address with every payment, so there is nothing to set up in the MoMo portal. The address ends in /wp-json/gravityextra-momo/v1/ipn.

Each notification is checked before anything happens: its signature must match your secret key, the partner code must be yours, and the order must be one this site created in the same mode. Then the add-on reads the payment back from MoMo and answers MoMo with an empty “204” response, as MoMo asks. A notification that arrives twice is acknowledged without changing the entry again.

The feed

• Transaction type: Products and Services, or Donations. The payment amount is the form total or one product field.
• Customer name, email and phone: optional; MoMo can use them to notify the customer. Vietnamese mobile numbers are sent in the 0xxxxxxxxx form; numbers that do not fit are left out.
• Order information: the text the customer sees on the MoMo payment page and in the app, and you see in the MoMo Business portal (merge tags work, up to 255 characters).
• Notifications: hold the form notifications until the customer has paid (on by default).

What the customer sees

The customer fills in the form and sees the total in dong, for example 1,250,000 ₫. After pressing the submit button they go to the MoMo payment page. On a computer they scan the QR code with the MoMo app and confirm; on a phone the MoMo app opens. They come back to your form page, where the add-on reads the payment from MoMo and shows your confirmation. If they decline the payment in the app or the page expires, they see that nothing was charged and can submit the form again. Messages from MoMo are in Vietnamese when your site language is Vietnamese.

Payment statuses

The entry screen

The MoMo box on the entry shows the status, the amount, the MoMo transaction ID and payment type, the order ID and the last result code MoMo reported. Refresh status reads the payment and its refunds from MoMo again. Test payments carry a “Test — test payment” badge. Users need the Gravity Forms capability to edit entries (administrators always can) to see the buttons.

Refunds

• Type the amount in whole dong in the refund field of a paid entry and press Refund with MoMo. The full remaining amount is filled in for you.
• The add-on reads the payment back first, then asks MoMo for the refund of the exact amount with a new refund order ID, and records it as soon as MoMo reports it successful.
• Several partial refunds are possible, each at least 1,000 VND, up to the paid amount. When the whole amount is refunded, the entry becomes Refunded.
• If MoMo is still processing a refund, the entry shows “Refund requested” and the status check records it later. A refund MoMo does not make frees the amount again.
• Refunds you make in the MoMo Business portal are recorded on the entry too, once.
• Each refund form can be used once, so pressing the button twice never refunds twice.

Testing with the MoMo test environment

1. Install the MoMo test app on a phone and sign in with a MoMo test account.
2. Keep the add-on in Test mode, paste your test partner code, access key and secret key and save. The connection line turns green.
3. Submit your form. On the MoMo payment page, scan the QR code with the MoMo test app and confirm.
4. Check the entry: Paid, with the MoMo transaction ID and a “Test — test payment” note. Try a partial refund.
5. Submit again and decline in the app: the entry becomes Cancelled and the customer is told nothing was charged.

Going live

• Paste the production partner code, access key and secret key from the MoMo Business portal, switch to Live and save.
• Make one small real payment and refund it.
• Your site must be reachable over https with pretty permalinks for live payment notifications.

For developers

The filter gravityextra_momo_request_fields can change the order information, the message language and the customer details. The amount, the order ID, the request type and the return and notification addresses are always set by the add-on. gravityextra_momo_max_amount lowers the largest payment and gravityextra_momo_payments_per_hour changes the hourly cap of new payments (300 by default).

// Show the class date in the order information of one form (ID 7) and use Vietnamese messages.
// The amount, order ID, request type and the return / notification addresses cannot be changed here.
add_filter( 'gravityextra_momo_request_fields', function ( $body, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $body;
    }
    $body['orderInfo'] = 'Class ' . rgar( $entry, '8' ) . ' / booking ' . rgar( $entry, 'id' );
    $body['lang']      = 'vi';
    return $body;
}, 10, 4 );

How it differs

• It connects to your own MoMo business account directly with the MoMo payment API, so the money is settled by MoMo to your account under your own MoMo agreement.
• It never trusts the return address or the payment notification on its own. The notification signature is checked with your secret key, and then the payment is read back from MoMo. Only a successful payment with the entry’s order ID and exact amount marks the entry Paid.
• It adds the Vietnamese dong to Gravity Forms with no decimals and comma thousands, so a total of 1,250,000 ₫ is sent to MoMo as exactly 1250000, never 1,250 and never one hundred times too large.
• Refunds, including several partial refunds, are made from the Gravity Forms entry and recorded once per MoMo refund, together with refunds you make in the MoMo Business portal.

Troubleshooting

Uninstall

Deleting the add-on from the Plugins screen removes its settings (including the encrypted keys), schedules and temporary data. Entries, notes and payments at MoMo stay as they are.

Plans: one site $49 a year, five sites $69 a year, unlimited sites $199 a year. See the Gravity Forms MoMo Premium Add-on page for details.