🎉 Celebrate with 10% OFF on All Products! Use Code: GFEX10 Or Buy Any 2+ Items for 30% OFF with Code: GFEX30!

Gravity Forms Pin Payments Setup Guide

Updated 8 min read Gravity Forms Payments & Pricing
On this page
  1. Step 1: Install and License the Add-on
  2. Step 2: Connect Your Pin Payments Account
  3. Sandbox is the default
  4. Paste your API keys
  5. 3D Secure (optional)
  6. Step 3: Add the Pin Payments Card Field
  7. Step 4: Create a Pin Payments Feed
  8. One-time payments
  9. Subscriptions
  10. Billing information
  11. Step 5: Set Up Webhooks
  12. Step 6: Manage Payments From the Entry
  13. Test in Sandbox Before Going Live
  14. Get Pin Payments test keys
  15. What to test
  16. Developer Filter: Webhook Signature Age
  17. Troubleshooting & FAQ
  18. The card field says card payments are not available yet.
  19. Customers see “Payments are temporarily unavailable.”
  20. The feed will not save.
  21. A customer clicked submit twice.
  22. Renewals or cancellations are not showing on the entry.
  23. Resource Hub

The Gravity Forms Pin Payments Premium Add-on connects Gravity Forms to your Pin Payments account so you can take card payments, authorise-and-capture payments and recurring subscriptions on your own forms. Customers type their card details into secure fields hosted by Pin Payments, so card numbers never pass through or get stored on your website. Refunds, captures and voids run from the Gravity Forms entry screen, and signed webhooks keep subscription renewals and cancellations in sync.

System Requirements & Prerequisites

  • WordPress: Version 6.5 or higher
  • PHP: Version 7.4 or higher
  • Gravity Forms: Version 2.9 or higher
  • Pin Payments account: the Test API is available as soon as you sign up; live payments need Pin Payments to approve your account
  • Currency: AUD (default), USD, NZD, SGD, EUR, GBP, CAD, HKD, JPY, MYR, THB, PHP, ZAR, IDR or TWD. Settling in a currency other than AUD needs an arrangement with Pin Payments
  • HTTPS: a public https address for webhooks (a staging site works for testing)
  • GravityExtra license: the Pin Payments add-on installed, activated and licensed

Step 1: Install and License the Add-on

  1. Go to Plugins → Add New → Upload Plugin, upload the add-on ZIP file and click Activate.
  2. Open Forms → Settings → Pin Payments.
  3. Enter your license key in the Gravity Extra License section and save. The Pin Payments settings appear once the license is active.

Step 2: Connect Your Pin Payments Account

Sandbox is the default

A new install always starts in Sandbox (Test API) mode. Payments go to the Pin Payments Test API and no real money moves. A yellow notice on the settings page says so, the live form shows a short test-card hint, and every sandbox entry is labelled. The add-on only uses the live API after you select Live and save.

Paste your API keys

In the Pin Payments dashboard open API Keys. The Test API and the live API have separate key pairs, so copy each pair into its own section:

  • Publishable key: used in the browser to turn card details into a single-use token. It cannot create charges.
  • Secret key: used by your site to create charges, refunds and subscriptions. It is stored as a password field and never printed on the page.
  • Webhook signing key (optional): leave empty when the add-on registers the webhook for you (see Step 5).

Click Save Settings. The add-on makes a read-only request to Pin Payments with your secret key and shows Connected when the key is accepted. Nothing is charged. If Pin Payments rejects the key, the field shows the reason.

Pin Payments settings in Gravity Forms with the Sandbox mode notice, Sandbox (Test API) selected, test publishable key, masked secret key and a Connected message
Sandbox mode selected and the test keys connected.

3D Secure (optional)

Under 3D Secure choose Off (default), On, continue without 3D Secure when the card does not support it, or On, decline cards that cannot use 3D Secure. When it is on, cardholders may be sent to their bank to approve a one-time payment and are then returned to your form, where they see the result. The entry stays Processing until the bank answers. Subscriptions are not sent through 3D Secure.

Step 3: Add the Pin Payments Card Field

Edit your form and add Pin Payments Card from the Pricing Fields group. The form also needs a product (and usually a Total field) so Gravity Forms can calculate the amount, plus Email and Address fields for the billing details Pin Payments requires. On the live form the field shows four secure inputs: name on card, card number, expiry and security code.

Pin Payments Card field on a Gravity Forms class booking form with name on card, card number, expiry and CVC inputs, a Sandbox test card hint and a Pay and book button
The card field on a class booking form in Sandbox mode.

How card data stays off your site

The four card inputs are small frames served by Pin Payments (Hosted Fields). When the customer clicks submit, Pin Payments checks the card and returns a single-use token. Only that token reaches WordPress, and the entry stores a masked card such as “Visa XXXX-XXXX-XXXX-0000”. The Gravity Forms Credit Card field is not used.

Step 4: Create a Pin Payments Feed

Go to Form Settings → Pin Payments → Add New. A feed can only be created on a form that has the Pin Payments Card field.

One-time payments

Choose Products and Services and select the Payment Amount (usually Form Total). The amount is always recalculated on the server from the entry, so a changed value in the browser cannot lower the price. Then choose the Payment action:

  • Charge immediately: the card is charged when the form is submitted.
  • Authorise only, capture later from the entry (within 7 days): the amount is held on the card. Pin Payments authorisations expire after seven days and can only be captured for the full amount.
Pin Payments feed with the name Class pack payment, Products and Services transaction type, Form Total payment amount and the Charge immediately payment action selected
A one-time payment feed that charges the form total immediately.

The optional Payment description appears in your Pin Payments dashboard and supports merge tags. It defaults to the form title.

Subscriptions

Choose Subscription to bill on a schedule. The add-on creates a Pin Payments customer, a plan and a subscription, so Pin Payments charges the renewals itself. Identical schedules reuse the same plan.

  • Billing Cycle: days, weeks, months or years.
  • Recurring Times: a fixed number of payments or infinite (until cancelled).
  • Setup Fee: a product charged with the first payment.
  • Trial and Trial length (days): the trial amount (0 for a free trial) is charged at sign-up and the recurring amount starts after that many days.
Pin Payments subscription feed with Unlimited Membership as the recurring amount, a monthly billing cycle, infinite recurring times, Joining Fee as setup fee and the trial length field
A monthly membership with a joining fee charged on the first payment.

Billing information

Pin Payments needs an email address and the card billing address, so Email, Address, City, State and Country are required mappings. First name, last name, Address 2, Zip and Phone are optional. Use short state codes such as VIC or NSW, as in Pin Payments’ own examples. Add Conditional Logic if only some submissions should be charged.

Step 5: Set Up Webhooks

Webhooks keep entries up to date with subscription renewals, failed renewals, cancellations, refunds, captures made in the dashboard and 3D Secure results. The webhook URL looks like https://yoursite.com/?callback=gfpinpaymentsaddon.

With Register this URL with Pin Payments automatically ticked (the default), the add-on registers the URL when you save your keys and stores the signing key for you. The settings page then shows “webhook endpoint registered with Pin Payments”.

Webhooks section of the Pin Payments add-on with the webhook URL, a webhook endpoint registered message, the automatic registration checkbox and the 3D Secure setting set to Off
Automatic webhook registration and the 3D Secure setting.

Local or private sites

Pin Payments only accepts public https addresses. On a local site the add-on shows a warning instead, and payments still work. To use a webhook you created yourself in the dashboard, paste its signing key into Webhook signing key for that mode.

Every webhook is checked against its Pin-Signature header, then the event is read again from the Pin Payments API before an entry changes. The same event is never applied twice.

Step 6: Manage Payments From the Entry

Each paid entry shows a Pin Payments box with the mode, status, charge or subscription token, masked card, customer token (for subscriptions), 3D Secure status and a link to the Pin Payments dashboard.

Pin Payments box on a Gravity Forms entry with the Sandbox mode notice, status Paid, charge token, Visa XXXX-XXXX-XXXX-0000, a dashboard link, an amount field in AUD and a Refund button
A paid entry with the refund action.
Entry status Actions What happens
Paid Refund with an amount Full or partial refund up to the remaining balance. Pin Payments reports refunds as pending first; the result arrives by webhook
Authorized Capture, Void authorisation Captures the full authorised amount, or releases the hold so the customer is not charged
Active subscription Gravity Forms Cancel Subscription Cancels the subscription in Pin Payments so no more renewals are charged

Each action asks you to confirm, is only available to users who can edit entries and adds a note to the entry. A charge that has been captured cannot be voided; refund it instead.

Test in Sandbox Before Going Live

Get Pin Payments test keys

  1. Sign up at pinpayments.com/get-started. Pin Payments gives new accounts access to the Test API straight away, with no application needed for testing.
  2. Confirm your email and log in at dashboard.pinpayments.com.
  3. Make sure the dashboard is in Test mode, open API Keys and copy the test publishable and secret keys into the Sandbox (Test API) keys section.
  4. For webhooks, test on a public https copy of your site, such as staging.

What to test

Pin Payments lists test cards on its Test Cards page (checked October 2026), for example 4200000000000000 for a successful payment and 4100000000000001 for a declined card. The same page lists cards for 3D Secure.

  • A successful payment, then a partial and a full refund from the entry.
  • A declined card: the customer sees a clear message and can try again.
  • An authorise-only feed: capture one payment and void another.
  • 3D Secure, if you turn it on.
  • A subscription with your setup fee or trial, then cancel it from the entry.
  • A webhook reaching your staging site.

When everything works, enter your live keys, select Live, save, and make one small real payment that you refund afterwards. Live keys only work after Pin Payments has activated your live account.

Developer Filter: Webhook Signature Age

Webhook signatures include a timestamp. By default the add-on rejects signatures older than 900 seconds (15 minutes) to block replayed requests. The gf_pinpayments_webhook_tolerance filter receives the number of seconds and returns a new limit.

functions.php
PHP
// Accept Pin Payments webhook signatures up to 30 minutes old
add_filter( 'gf_pinpayments_webhook_tolerance', function( $seconds ) {
    return 1800;
} );

Troubleshooting & FAQ

The card field says card payments are not available yet.

The publishable key for the current mode is missing. Open Forms → Settings → Pin Payments, check which mode is selected and enter both keys for that mode.

Customers see “Payments are temporarily unavailable.”

The add-on stopped before charging. Common causes: the secret key for the current mode is missing or rejected, the Gravity Forms currency is not one Pin Payments supports, or the amount is below the Pin Payments minimum (for example A$1.00). Turn on Forms → Settings → Logging to see the exact reason.

The feed will not save.

Pin Payments needs the billing email, address, city, state and country. Map all five under Billing Information and save again.

A customer clicked submit twice.

Each submission and each card token can only be charged once, so a double click makes one charge. If the connection to Pin Payments times out, the customer is asked to contact you before paying again; check your dashboard first.

Renewals or cancellations are not showing on the entry.

Check that the settings page shows a registered webhook for the current mode, or that your own signing key is entered. Webhooks cannot reach a local site.

Resource Hub

Still need help?

Our support team answers tickets every day, usually within a few hours.

0
0
Your Cart
Your cart is emptyReturn to Shop
🔥 FREQUENTLY BOUGHT TOGETHER
Complete Combo & Save 40%!
ITEM IN YOUR CART
Gravity Forms Klaviyo Add-on
$39.00/yr
+
🎁 RECOMMENDED ADD-ON SAVE 40% OFF
Original Price: $39.00/yr
Bundle Special Price: $23.40/yr