Gravity Forms Viva.com Premium Add-on Setup Guide

The Gravity Forms Viva.com Premium Add-on takes payments with your forms through Viva.com Smart Checkout. When a visitor submits the form, the add-on creates a Viva.com payment order for the exact total Gravity Forms worked out on the server and sends the visitor to the secure Smart Checkout page. The visitor pays there by card, digital wallet or a local payment method your Viva.com account offers, so card details never reach your website. Before an entry changes, the add-on retrieves the transaction from Viva.com and checks the order code, the amount, the currency and the status.

This guide covers the setup, the payment source, the webhook, the feed, payments, refunds, subscriptions and going live. The add-on costs one site $49 a year, five sites $69 a year, unlimited sites $199 a year.

What you need

• WordPress 6.5 or newer, PHP 7.4 or newer (with the openssl extension) and Gravity Forms 2.9 or newer.
• A Viva.com business account. Start with a free demo account for testing; the live account is separate and has its own credentials.
• From Settings → API Access in Viva.com: the Smart Checkout client ID and client secret, and the Merchant ID and API Key (needed for refunds, subscriptions and the webhook).
• The Gravity Forms currency set to one of euro (EUR), pound sterling (GBP), złoty (PLN), leu (RON), koruna (CZK), forint (HUF), Swedish krona (SEK) and Danish krone (DKK). A currency other than the one of your Viva.com account needs Multicurrency on your account.
• Your site public and on HTTPS, so Viva.com can reach the webhook address.
• A form with at least one product field (or a total).

The add-on talks to accounts.vivapayments.com (access tokens), api.vivapayments.com (payment orders and transactions) and www.vivapayments.com (refunds, recurring charges and the webhook key), or their demo versions, and sends customers to the Smart Checkout page. Apart from that, it checks gravityextra.com for your licence and plugin updates.

Install and activate

1. Upload the zip in Plugins → Add New → Upload Plugin and activate it.
2. Open Forms → Settings → Viva.com, enter your GravityExtra licence key and press Activate License.
3. The Viva.com account and Payment source sections appear once the licence is active. Payments, webhooks, refunds and recurring charges work only with an active licence.

Connect your Viva.com account

1. Leave Environment on Demo for now.
2. Paste the demo Smart Checkout client ID (it ends with .apps.vivapayments.com) and the client secret.
3. Paste the demo Merchant ID and API Key.
4. Enter the payment source code of this website (see the next step). Leave it empty to use your default source.
5. Save. The Account line turns green and shows masked values. Secrets are stored encrypted and never shown again.

Create the payment source

Viva.com sends the customer back to the Success URL or the Failure URL of a payment source. In Viva.com, open Sales → Online payments → Websites/Apps and add a source:

1. Protocol https and the domain name shown in the add-on settings.
2. Integration method Redirection/Native Checkout v2.
3. Copy the Success URL and the Failure URL from the add-on settings (for a site at the domain root they are ?gfviva=success and ?gfviva=fail).
4. Upload your logo: it is shown on the payment page.
5. Save and copy the four-digit source code into the add-on settings.

Add the webhook

1. In the add-on settings, press Get the Demo webhook verification key. The add-on asks Viva.com for the key with your Merchant ID and API Key and saves it.
2. In Viva.com, open Settings → API Access → Webhooks and press Create Webhook.
3. Paste the webhook address from the add-on settings and press Verify. Viva.com calls the address, and the add-on answers with the key.
4. Choose Transaction Payment Created, tick Active and save. Add the same address for Transaction Failed and Transaction Reversal Created.

Viva.com webhooks are not signed. The add-on therefore treats every webhook as a hint only: it retrieves the transaction from Viva.com with your own credentials and checks it against the entry before anything changes. The last accepted webhook is shown in the settings.

Add a feed to your form

1. Open the form, then Settings → Viva.com → Add New.
2. Choose Products and Services for a one-off payment, usually with the Form Total, or Subscription (see below).
3. Map the first name, last name and e-mail. They are filled in on the Viva.com page, so the customer does not type them again.
4. Set the payment description, shown to the customer and on the receipt. Merge tags work, for example Booking #{entry_id}.
5. Keep Send form notifications only after the customer has paid ticked, so your booking e-mails go out for paid entries only.

How a payment works

1. The visitor submits the form. Gravity Forms works out the total on the server, and the add-on creates a Viva.com payment order for that amount in the smallest currency unit (cents), with your source code and the entry number as the merchant reference.
2. The visitor goes straight to Smart Checkout and pays there.
3. Viva.com sends the visitor back to the Success URL with the transaction id. The add-on retrieves that transaction from Viva.com and checks the order code, the amount, the currency and the status. Only then is the entry marked Paid, with the transaction id and the card in the notes.
4. The visitor sees your confirmation on the form page. If the payment is still pending, the page waits and checks Viva.com again by itself.
5. The Transaction Payment Created webhook arrives as well and is checked the same way. A payment is never completed twice.

When the visitor cancels on the Viva.com page or the payment does not go through, your form page says that nothing was charged and offers a link back to the same payment page, which stays open for 30 minutes.

Refunds

Open a paid entry. The Viva.com box shows the status, the order code, the transaction, the card used and the amounts. Type an amount and press Refund to refund all or part of the payment. The add-on sends the refund to Viva.com with a one-time idempotency key, so a double click never refunds twice, and the entry becomes Partially Refunded or Refunded as soon as Viva.com answers. Refunds need Allow refunds in Viva.com Settings → API Access.

Refunds you make in your Viva.com account are recorded on the entry too, when the Transaction Reversal Created webhook arrives; the add-on retrieves the refund and checks that it belongs to this payment and fits in what is left.

Subscriptions

Choose Subscription in the feed, the recurring amount (usually the form total), the billing cycle (every so many days, weeks, months or years) and the number of payments, or no limit. Trial periods and setup fees are not offered.

1. Tick Allow recurring payments and pre-auth captures via API in Viva.com Settings → API Access. The Merchant ID and API Key must be saved.
2. The customer pays the first period on Smart Checkout. The payment order allows recurring payments, so Viva.com offers only payment methods that support them.
3. After the first payment is checked, the entry becomes Active and the next charge date is set.
4. A WordPress scheduled task checks every hour and charges the same payment method when a period is due. Each new transaction is retrieved and checked before it is recorded on the entry.
5. A declined charge is tried again the next day; after three declines the subscription is cancelled. When the number of payments is reached, the subscription expires.

WordPress runs scheduled tasks when the site has visitors. For exact timing on a quiet site, let your host call wp-cron.php every few minutes. Refund subscription payments in your Viva.com account.

Demo and Live

• In Demo, entries are marked as test payments and no money moves. Pay with the test cards listed in the Viva.com developer portal, for amounts of 0,30 € or more.
• For Live, paste the live credentials, create the payment source and the webhook in your live account, choose Live and save.
• Make one small real payment and refund it from the entry.
• Entries remember the environment they were paid in; webhooks and refunds use the credentials of that environment.

For developers

The webhook address can be changed with the gravityextra_viva_webhook_url filter; update the address in Viva.com after changing it. Amounts, the currency and the order are always set by the add-on.

// Receive Viva.com webhooks on another public address of the same site
// (for example when the home page is behind a login).
add_filter( 'gravityextra_viva_webhook_url', function ( $url, $env ) {
    return add_query_arg( array( 'callback' => 'gfviva', 'viva_env' => $env ), home_url( '/pay/' ) );
}, 10, 2 );

Troubleshooting

Privacy

The add-on sends Viva.com the amount, the currency, the payment description, the entry and form numbers, and the customer name and e-mail when you map them. Card numbers are entered on the Viva.com page and never reach your site. Client secrets, API keys and access tokens are stored encrypted with keys from your site’s WordPress salts. Uninstalling the add-on removes its settings, including the credentials, and stops the recurring task.