Gravity Forms toyyibPay Premium Add-on Setup Guide

The Gravity Forms toyyibPay Premium Add-on lets your Gravity Forms take payments in Malaysian Ringgit through toyyibPay. When a form is submitted, the add-on creates a toyyibPay bill for the exact total and sends the customer to the toyyibPay page, where they pay with FPX online banking or a card. When they come back, or when toyyibPay sends its callback, the add-on reads the bill back from toyyibPay and only then marks the entry as paid. This guide covers every setting, the feed, what happens during a payment, testing in the toyyibPay Sandbox and going live.

How a payment works

1. The customer fills in the form. Gravity Forms works out the total; the add-on checks it is a Ringgit amount with at most two decimals and at least RM1.00, and that the email and phone are valid.
2. The entry is saved with the status Processing. The add-on creates a bill (createBill) with the total in sen, your category, the bill name and description from the feed, the payer’s name, email and phone, a unique order reference, a signed return link and the callback address.
3. The customer is sent to the toyyibPay page for that bill and pays with FPX or a card. Bank and card details are entered on toyyibPay, never on your website.
4. When the customer returns, the add-on ignores the status in the address and reads the bill’s transactions from toyyibPay. A successful transaction for the right reference and amount marks the entry Paid; a pending FPX payment shows a page that checks again by itself.
5. toyyibPay also posts a callback. The add-on checks its hash with your key, then reads the bill back again. The same payment is never completed twice.
6. Every five minutes a status check reads bills still waiting. When a bill has expired without a payment, it is closed at toyyibPay and the entry is cancelled.

Install and activate

1. In WordPress, go to Plugins → Add New → Upload Plugin, choose the zip file and activate the add-on.
2. Go to Forms → Settings → toyyibPay and activate your GravityExtra license key. The settings appear once the license is active.
3. Make sure Forms → Settings → Currency is Malaysian Ringgit.

Settings

The settings page has one section for your toyyibPay account. Both environments are shown; only the chosen one is used for new bills. Entries always stay with the environment their bill was created in, so switching from Sandbox to Live never confuses earlier test entries.

Where to find the key and the category code

Log in to your toyyibPay account. The User Secret Key is in the settings of your account. For the category, open Category, create one (for example “Online orders”) and copy its code, a short string of letters and digits. Do the same in your Sandbox account on dev.toyyibpay.com for the Sandbox fields.

When you save, the add-on asks toyyibPay for the category with the key you typed. If toyyibPay does not know the key, or the category belongs to another account, the field shows toyyibPay’s answer and nothing is saved. If your server cannot reach toyyibPay at that moment, the settings are saved and the connection line says it could not confirm them yet.

The callback address

The add-on sends its callback address with every bill, so there is nothing to set up in your toyyibPay account. The address is shown on the settings page for reference, together with the time of the last verified callback. toyyibPay cannot send callbacks to a local test site; there the return page and the status check confirm payments instead.

The feed

Open your form, go to Settings → toyyibPay and add a feed.

• Transaction type: Products and Services, or Donations. The payment amount is usually the form total.
• Payer details: map the first and last name, the email and the phone. Email and phone are required: toyyibPay sends its receipt to the email and asks for the phone on every bill.
• Bill name: the title on the toyyibPay page, up to 30 characters. toyyibPay allows letters, digits, spaces and underscores, so other characters become spaces. The default is the form title.
• Bill description: up to 100 characters with the same rules. The default is “Order” and the entry number.
• Notifications: tick to send the form’s notifications only after the customer has paid. They are sent once, at the moment the payment is confirmed.
• Conditional logic: as with any Gravity Forms feed, you can run it only when a condition is met.

The form and the toyyibPay page

The form looks like any Gravity Forms form with products and a total. After submission the customer goes straight to the toyyibPay page for the bill. There they choose their bank for FPX or pay by card, depending on your setting. If they cancel or the bank declines, nothing is charged and the entry shows Failed; they can still pay the same bill until it expires.

Payment statuses

The entry screen

Each entry paid through toyyibPay has a toyyibPay box with the status, the amount, the bill code, the order reference, the toyyibPay invoice number and the payment channel. Sandbox entries carry a “Sandbox — test payment” badge. The Refresh status button reads the bill from toyyibPay at once. The entry notes keep the history: bill created, payment received, failed or cancelled.

Refunds

toyyibPay has no refund function in its API, so the add-on does not offer a refund button. Arrange the refund from your toyyibPay account, then change the payment status of the entry yourself if you want it to show Refunded.

Testing in the Sandbox

1. Create a Sandbox account on dev.toyyibpay.com and a category in it.
2. Paste the Sandbox User Secret Key and category code, keep the environment on Sandbox and save. The connection line should say “Connected to toyyibPay (Sandbox)”.
3. Submit your form. On the toyyibPay Sandbox page, pay with the bank simulator.
4. Back on your site, the confirmation shows and the entry is Paid. Try a failed payment too, and leave one bill unpaid to see it cancelled after it expires.

Going live

1. Paste the Live User Secret Key and the code of a category in your live account.
2. Switch the environment to Live and save.
3. Make one small real payment with FPX and check the entry and your toyyibPay account.

For developers

The filter gravityextra_toyyibpay_bill_fields lets you change the bill fields before the bill is created, for example the receipt email text. The amount, price setting, order reference, category, return link and callback address are set again after the filter, so they cannot be changed by mistake.

// Send a custom thank-you line in the toyyibPay receipt email for one form (ID 7).
add_filter( 'gravityextra_toyyibpay_bill_fields', function ( $fields, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $fields;
    }
    $fields['billContentEmail'] = 'Terima kasih! We will deliver within 2 working days.';
    return $fields;
}, 10, 4 );

• gravityextra_toyyibpay_callback_url: the callback address sent with bills.
• gravityextra_toyyibpay_rate_limit: the per-visitor limits per minute (bill creation 10, return page 30, callback 120).
• gravityextra_toyyibpay_bills_per_hour: the cap on new bills per hour for the whole site (300).

How it differs

• Nothing is trusted from the browser or the callback: every result is read back from toyyibPay with your key (getBillTransactions) and checked against the entry’s order reference and amount before the entry changes.
• Each callback must carry the right hash for the key of the environment the bill was created in; a repeated callback is dropped, and a payment can only be completed once.
• The bill is for the exact Gravity Forms total in sen. Totals with more than two decimals, below RM1.00 or in another currency are refused before a bill is made.
• Each payment attempt gets its own order reference, and bills from several sites on one toyyibPay account never mix.
• Expired bills are closed at toyyibPay, so an old payment link cannot be paid after the entry was cancelled.
• Bill creation, the return page and the callback have per-visitor limits, and new bills have an hourly cap, so a flood of form posts cannot create bills without end.

Troubleshooting

Uninstall

Uninstalling from Forms → Settings → Uninstall removes the settings (including the encrypted keys), the status check schedule and the add-on’s temporary data. Entries and their notes stay, and bills and payments at toyyibPay are not touched.

Plans: one site $49 a year, five sites $69 a year, unlimited sites $199 a year. Get the add-on on the Gravity Forms toyyibPay Premium Add-on page.