Gravity Forms Openpay Premium Add-on Setup Guide

The Gravity Forms Openpay Premium Add-on lets your Gravity Forms take card payments through Openpay, the online payment service of BBVA, for businesses in Mexico, Colombia and Peru. When a form is submitted, the add-on creates an Openpay charge for the exact total in your country’s currency and sends the customer to the Openpay payment page, where they enter their card. Card details never touch your website. When the customer comes back, or when Openpay sends a webhook, the add-on reads the charge back from Openpay and only then marks the entry as paid. Refunds are made from the entry screen. This guide covers every setting, the feed, what happens during a payment, webhooks, refunds, testing in the sandbox and going live.

Countries and currencies

Openpay runs a separate service in each country, and each account takes payments in its own currency. Choose your country in the settings; the add-on then uses the matching servers and currency for every charge, and refuses forms in any other currency before anything is sent.

Gravity Forms has Mexican pesos built in, but not Colombian pesos or Peruvian soles. The add-on adds both to the Gravity Forms currency list, with their own formats ($ 1.250.000,00 for Colombia and S/ 1,250.00 for Peru), so you can choose them in Forms → Settings and prices are read correctly. A currency another plugin already defines is left as it is.

Amounts are sent to Openpay as a number with at most two decimals (for example 1499.00 pesos), and the add-on keeps the exact amount on the entry in cents, so it can compare it with what Openpay reports to the cent. Totals below 1.00 are refused, and so are totals with more than two decimals.

How a payment works

1. The customer fills in the form. Gravity Forms works out the total; the add-on checks that it is an amount in your Openpay currency with at most two decimals.
2. The entry is saved with the status Processing. The add-on creates an Openpay card charge on your server for the total, with a unique order reference, a description, the customer’s name, email and phone, and a signed return address. The charge is created with confirm off, which tells Openpay to collect the card on its own payment page.
3. Openpay answers with the charge and the address of its payment page. Before the customer is sent there, the add-on checks that the charge is waiting, carries the right order reference, amount and currency, and that the page is on an Openpay address of your country. If anything differs, the customer is told nothing was charged and the entry is marked Failed.
4. The customer enters the card on the Openpay page (the bank may ask for an extra confirmation there). Card details never reach your website.
5. Openpay sends the customer back to your form page. The add-on reads the charge from Openpay and shows your confirmation as soon as the charge is completed. Openpay also sends a webhook, which makes the add-on read the charge again.

Install and activate

1. In WordPress go to Plugins → Add New → Upload Plugin, upload the zip and activate it.
2. Open Forms → Settings → Openpay, 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 the one of your Openpay country.

Settings

Open Forms → Settings → Openpay. Each mode has its own merchant ID and private key; only the keys of the mode you choose are used for new charges. An entry always keeps the mode and country it was created in, so a charge started in Sandbox is still read from the sandbox after you switch to Live.

Getting your keys

1. Sandbox: sign in to the Openpay sandbox dashboard of your country and open the API keys. Copy the merchant ID and the private key into the Sandbox fields and save. When you save, the add-on reads your merchant from Openpay with them (a read that changes nothing); the connection line turns green when Openpay accepts them.
2. Production: once Openpay has approved your account for live payments, copy the merchant ID and private key from the production dashboard into the Live fields.
3. The private keys are stored encrypted and only ever shown masked (the first four and the last four characters).

Webhooks

Openpay webhooks do not carry a signature. Instead, Openpay lets you protect the webhook address with HTTP authentication, and the add-on requires it: it creates a user and a long random password for you, and every webhook without exactly those credentials is refused. Even an authenticated webhook decides nothing on its own: the add-on reads the charge back from Openpay and checks it against the entry before anything changes. To set it up:

1. Copy the webhook address, the user and the password from the Webhook block of the settings page.
2. In the Openpay dashboard, open your business profile (click your name), go to Webhooks and choose Add webhook.
3. Paste the address, turn on HTTP authentication and enter the user and password. Save.
4. Openpay sends a verification code to the address. Reload the settings page: the code appears in the Webhook block. Back in Openpay, choose Verify and enter the code to activate the webhook.

Do the same in the production dashboard when you go live. If you ever need a new code, choose Forward code in Openpay.

The feed

Open your form, go to Settings → Openpay and add a feed. Choose Products and Services or Donations and the payment amount (usually the form total). Then map the customer fields: Openpay needs the customer’s first name and email for a charge on its payment page, and the last name and phone are added when you map them. A phone is sent as the national number of your country (ten digits in Mexico and Colombia, nine in Peru); a country code such as +52 is removed, and numbers that do not fit are left out.

• Description: shown with the charge in Openpay, up to 250 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 Openpay page

Use Gravity Forms product, quantity, option and total fields as usual. The amount sent to Openpay is the total Gravity Forms calculated on your server, 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 Openpay page next.

When the customer comes back, they see your normal confirmation as soon as Openpay reports the charge as completed. If the bank is still checking the card, a short waiting message checks again by itself for about a minute, then tells the customer that the entry updates by itself.

Payment statuses

The entry screen

Every Openpay entry has an Openpay box on the right with the status, the amount, the charge id, the order reference, the Openpay country, the card brand and last four digits, Openpay’s message if the card was declined, and any refund. Sandbox payments carry a Sandbox badge.

• Refresh status reads the charge from Openpay again and applies it.
• Refund with Openpay sends a full or partial refund to the customer’s card. Type the amount (1499.00 or 1.499,00 both work; the field starts with the full amount) and confirm.

Refunds

Openpay keeps one refund per card charge, full or partial. Before it is sent, the add-on reads the charge from Openpay and checks that it is completed for the entry amount and has no refund yet. Each refund form can be used once, so a double click or a reloaded page cannot refund twice. The refund is recorded on the entry, as a transaction with a note, from Openpay’s answer; when the whole amount was refunded the entry becomes Refunded. If Openpay does not answer, the request is kept as waiting and the status check reads the charge until Openpay shows the refund (or, after an hour without one, frees it with a note). Refunds you make in the Openpay dashboard are recorded too, the next time the charge is read.

Testing in the sandbox

1. Leave the mode on Sandbox and save your sandbox merchant ID and private key.
2. Set up the sandbox webhook as described above and verify it.
3. Open the form on your site, fill it in and continue to payment.
4. On the Openpay sandbox page, pay with one of the test cards from the Openpay testing documentation.
5. 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.
6. Pay another test entry with a test card that Openpay declines: the entry becomes Failed.
7. Refund part of a paid test payment from the entry screen and watch it appear as a refund transaction.

Going live

1. Paste the production merchant ID and private key into the Live fields.
2. Add and verify the webhook in the production dashboard with the same address, user and password.
3. Switch the mode to Live and save. The connection line should say Connected to Openpay with your country and Live.
4. Make one small real payment, check the entry and refund it from the entry screen.

For developers

• gravityextra_openpay_charge_fields filters the charge before it is sent. The description and the customer block can be changed; the amount, the currency, the order reference, the method, the confirm flag and the return address cannot, and a card source or other card fields are removed.
• gravityextra_openpay_max_cents lowers the largest charge the site accepts, in cents (default 999,999.99 for MXN and PEN, 99,999,999.99 for COP).
• gravityextra_openpay_rate_limit changes the per-visitor limits (payment starts 10, return page 30, webhooks 120 per minute).
• gravityextra_openpay_payments_per_hour changes the site-wide cap of new charges per hour (300).
• gravityextra_openpay_webhook_base changes the base of the webhook address (for a site behind a proxy).

// Put the workshop date in the Openpay charge description for one form (ID 7).
add_filter( 'gravityextra_openpay_charge_fields', function ( $charge, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $charge;
    }
    $charge['description'] = 'Workshop on ' . rgar( $entry, '8' ) . ' #' . rgar( $entry, 'id' );
    return $charge;
}, 10, 4 );

How it differs

• Card details are entered on the Openpay page: the charge is created with confirm off, so no card number, token or card form is ever on your site.
• Nothing is trusted from the browser or the webhook body: every result is read back from Openpay and checked against the entry’s order reference, amount and currency before the entry changes. The charge id Openpay adds to the return address is ignored; the entry’s own charge is read.
• Openpay webhooks have no signature, so the webhook address is protected with an HTTP authentication user and password the add-on creates, compared in constant time; a repeated webhook is dropped, so a payment can only be completed once.
• One add-on for Mexico, Colombia and Peru: the right servers and currency for your country, and every entry keeps the mode and country it was created in.
• Keys are checked with Openpay when you save and stored encrypted; the public key is refused.
• Refunds from the entry screen are checked against Openpay first, protected by a one-time form, and kept as waiting when Openpay does not answer, so a refund is never sent twice.
• Payment creation, the return page and webhooks have per-visitor limits, and new charges have an hourly cap, so a flood of form posts cannot create charges without end.

Troubleshooting

Uninstall

Uninstalling the add-on from Forms → Settings → Uninstall removes its settings (including the encrypted private keys), the webhook user and password, the verification code, the status check schedule, its locks, counters and cached checks. Entries, their notes and transactions stay in Gravity Forms, and charges and refunds at Openpay are not touched. Remove the webhook in the Openpay dashboard too.

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