Gravity Forms SSLCommerz Premium Add-on Setup Guide

The Gravity Forms SSLCommerz Premium Add-on connects Gravity Forms to your own SSLCommerz store in Bangladesh. When a form with an SSLCommerz feed is submitted, the add-on starts an SSLCommerz payment session for the exact total Gravity Forms calculated and sends the customer to the SSLCommerz payment page, where they pay with a card, mobile banking or internet banking, whatever is active on your store. Payment details are entered at SSLCommerz, never on your website.

When SSLCommerz reports the payment, the add-on checks the IPN signature with your store password, reads the payment back with the SSLCommerz Order Validation API and only then marks the entry Paid, with the bank transaction ID as the transaction ID. This guide covers installation, currencies, every setting, the IPN, the feed, what the customer sees, the payment statuses, refunds, testing with a sandbox store 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 → SSLCommerz and activate your licence key. The SSLCommerz settings appear once the licence is active.
3. In Forms → Settings, set the Gravity Forms currency to Bangladeshi Taka (or one of the other currencies below).

Currencies and amounts

Gravity Forms does not include the Bangladeshi taka out of the box. The add-on adds the taka (and the Indian rupee) to the Gravity Forms currency list as soon as it is active, with two decimals, and never changes a currency that another plugin already defined. SSLCommerz settles in taka: forms in US dollars, euros, Singapore dollars, rupees or ringgit are converted to taka by SSLCommerz at its current rate, while the entry keeps the amount in the form currency.

The amount is worked out on your server from the entry, never from the browser. A total with more than two decimals is refused before anything is sent, so the customer is never charged a rounded amount. Taka payments go from 10.00 to 500,000.00 BDT, the range SSLCommerz takes; for other currencies the add-on takes 1.00 to 500,000.00 and SSLCommerz checks the converted amount. A filter can lower the largest amount.

Settings

The IPN

SSLCommerz tells your site about payments with an IPN (instant payment notification): a signed message posted to your site. The add-on sends its IPN address with every payment session, so there is nothing to set up for it to work. You can also enter the address in your SSLCommerz merchant panel (My Stores → IPN Settings) so that every payment of the store is reported.

1. Copy the IPN address from the IPN line of the add-on settings. It ends in /wp-json/gravityextra-sslc/v1/ipn.
2. Optionally, enter it in the IPN settings of your store in the SSLCommerz merchant panel.
3. If your server has a firewall, allow the SSLCommerz IPN addresses SSLCommerz lists in its documentation, on ports 80 and 443.

Each IPN is checked before anything happens: its verify_sign must match the signed fields and your store password, the transaction ID and status must be signed, and the transaction must be one this site started in the same mode. Then the add-on reads the payment back from SSLCommerz. An IPN that arrives twice is acknowledged without changing the entry again. If the read-back fails, the add-on answers with an error so SSLCommerz sends the IPN again.

The feed

• Transaction type: Products and Services, or Donations. The payment amount is the form total or one product field.
• Name, email and phone are required by SSLCommerz: map them to your form fields. Address, city, postcode and country are optional; SSLCommerz asks for them on every payment, so empty ones are sent as “N/A” (and Bangladesh for the country).
• Description: the product name shown in your SSLCommerz merchant panel (merge tags work).
• Product category: a short category such as Education, Services or Donation.
• 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, for example ৳ 2,450.00. After pressing the submit button they go to the SSLCommerz payment page and choose a card, mobile banking or internet banking. After paying they come back to your form page, where the add-on reads the payment from SSLCommerz and shows your confirmation. If the payment fails or they cancel, they see that nothing was charged and can return to the form.

Payment statuses

The entry screen

The SSLCommerz box on the entry shows the status, the amount, the bank transaction ID, the payment method, your transaction ID, the SSLCommerz validation ID and the last status SSLCommerz reported. Refresh status reads the payment from SSLCommerz again. Test payments carry a “Test — test payment” badge, and a payment SSLCommerz marks as high risk gets a warning note so you can check it before you deliver. Users need the Gravity Forms capability to edit entries (administrators always can) to see the buttons.

Refunds

• Type the amount in the refund field of a paid taka entry and press Refund with SSLCommerz. The full remaining amount is filled in for you.
• The add-on reads the payment back first, then sends the refund to SSLCommerz with a unique refund ID, and records it when SSLCommerz reports it as refunded.
• Several partial refunds are possible up to the paid amount. When the whole amount is refunded, the entry becomes Refunded.
• If SSLCommerz takes a moment, the entry shows “Refund requested” and the status check records it later. A refund SSLCommerz cancels frees the amount again.
• If SSLCommerz does not answer a refund request, the request stays reserved: check your merchant panel, then use Release the unanswered refund request if no refund was made.
• SSLCommerz requires the public IP address of your server to be registered for refunds in the live system; ask SSLCommerz support to add it.
• Payments made in another currency than taka, and refunds you make in the merchant panel, are handled in the panel.

Testing with a sandbox store

1. Register for an SSLCommerz sandbox store and note its store ID and store password.
2. Keep the add-on in Test mode, enter the sandbox store ID and password and save. The connection line turns green.
3. Submit your form and pay on the sandbox payment page with an SSLCommerz test card.
4. Check the entry: Paid, with the bank transaction ID and a “Test — test payment” note. Try a partial refund.
5. Try a cancelled payment: the customer sees that nothing was charged.

Going live

• Enter the live store ID and store password from SSLCommerz, switch to Live and save.
• Make one small real payment and refund it.
• Your site must be reachable from the internet for live IPNs.

For developers

The filter gravityextra_sslcommerz_request_fields can change the customer fields, the product name and the product category. The amount, the currency, the transaction ID and the return addresses are always set by the add-on. gravityextra_sslcommerz_max_minor lowers the largest payment and gravityextra_sslcommerz_payments_per_hour changes the hourly cap of new payments (300 by default).

// Put the class date in the product name of one form (ID 7) and use a fixed category.
// The amount, currency, transaction ID and the return addresses cannot be changed here.
add_filter( 'gravityextra_sslcommerz_request_fields', function ( $body, $feed, $entry, $form ) {
    if ( 7 !== (int) rgar( $form, 'id' ) ) {
        return $body;
    }
    $body['product_name']     = 'Class ' . rgar( $entry, '9' ) . ' / booking ' . rgar( $entry, 'id' );
    $body['product_category'] = 'Education';
    return $body;
}, 10, 4 );

How it differs

• It connects to your own SSLCommerz store directly with the SSLCommerz API, so SSLCommerz settles the money to you under your own merchant agreement, and the payment page shows every method you have switched on.
• It never trusts the data posted back to your site or the IPN on its own. The IPN signature is checked with your store password, and then the payment is read back from SSLCommerz with the Order Validation API. Only a valid payment with the entry’s transaction ID, amount and currency marks the entry Paid.
• It adds the taka and the rupee to Gravity Forms, so a total of ৳ 2,450.00 is shown, sent and stored as exactly 2450.00, never misread or rounded.
• Refunds, including several partial refunds, are made from the Gravity Forms entry and recorded once per SSLCommerz refund.

Troubleshooting

Uninstall

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

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