Troubleshooting Payment Problems

If a payment is not working as expected in VendorHearth Pro, the problem is often related to Square credentials, environment settings, webhook configuration, or the payment record itself.

Use the following checks before attempting to manually change a vendor’s payment status.

Payment Option Is Not Working #

If vendors cannot complete a Square payment, first review your VendorHearth Square configuration.

Verify:

• Square is configured as the payment gateway.
• The correct environment is selected.
• The Application ID is correct.
• The Location ID is correct.
• The Access Token is correct.
• Your website is using HTTPS.

If you recently switched from Sandbox to Production, make sure you replaced all Sandbox credentials with Production credentials.

Sandbox Works but Production Does Not #

Sandbox and Production are separate Square environments.

A successful Sandbox test does not automatically mean your Production configuration is complete.

Verify your Production:

• Application ID
• Location ID
• Access Token
• Webhook subscription
• Webhook Signature Key

Do not use Sandbox credentials while VendorHearth is set to Production.

Square Shows the Payment but VendorHearth Does Not #

If Square shows a successful payment but VendorHearth has not reflected the expected update, check the webhook configuration.

Verify:

1. The webhook subscription is active.
2. The notification URL matches the Webhook URL displayed by VendorHearth.
3. The webhook is subscribed to payment.updated.
4. The webhook exists in the correct Square environment.
5. The Signature Key in VendorHearth matches the Square subscription.
6. Your website is publicly accessible over HTTPS.

Do not immediately create a manual payment record.

The Square transaction may already exist and simply be missing its corresponding update in VendorHearth.

VendorHearth Shows the Wrong Payment Status #

First verify the actual transaction.

Check:

• The vendor
• The event
• The application
• The Square transaction, if applicable
• The payment amount
• Whether the payment was online, manual, or historical

Correct the underlying record when possible instead of creating additional payment entries.

A Vendor Says They Paid #

Do not manually mark the vendor as paid based only on the vendor’s statement.

If they paid through Square, locate the transaction in Square.

If the payment was received through another approved method, verify that payment through your organization’s records before entering it manually.

Duplicate Payment Records #

If the same payment appears to have been recorded more than once, determine whether one record is a Square transaction and another is a manual record.

A common cause of duplicate records is manually recording a payment after a Square transaction occurred but before its VendorHearth status was properly updated.

Investigate the original transaction before adding another payment record.

Webhook Signature Errors #

If Square payment updates are not being accepted, verify the Webhook Signature Key stored in VendorHearth.

The key must correspond to the webhook subscription being used.

If you deleted and recreated the Square webhook, review the new subscription and update the Signature Key in VendorHearth if necessary.

Wrong Square Location #

Square accounts can contain multiple locations.

If payments are not behaving as expected, verify that the Location ID entered in VendorHearth belongs to the Square location you intend to use.

Do not assume the first location listed in Square is necessarily the correct one.

Access Token Problems #

The Access Token allows VendorHearth to communicate with Square.

If the token is incorrect, belongs to the wrong environment, has been replaced, or is otherwise no longer valid, payment communication may fail.

Retrieve the appropriate token from your Square Developer application and update VendorHearth if necessary.

Never publish your Access Token while troubleshooting.

Payment Was Received Outside Square #

If the vendor legitimately paid outside the VendorHearth Square checkout, use the appropriate manual payment workflow.

Do not attempt to create a Square transaction afterward simply to make the payment appear in Square.

The VendorHearth record should reflect how the payment actually occurred.

Imported Vendor Shows as Unpaid #

If you are importing an application for a vendor who already paid before the migration, use the appropriate Confirmed / Already Paid option.

VendorHearth can create a labeled historical/manual payment record for the imported application.

This avoids requiring the vendor to pay a second time.

Check System Readiness #

If payment problems appear to be part of a larger VendorHearth configuration issue, review:

VendorHearth → System Readiness

System Readiness can help identify configuration problems that may affect normal operation.

Resolve any relevant warnings before continuing to troubleshoot individual payments.

Do Not Share Private Credentials #

If you need assistance troubleshooting Square, never send your:

• Access Token
• Webhook Signature Key
• Passwords
• Other private authentication credentials

Screenshots should be reviewed carefully before being shared.

Hide or remove sensitive information first.

Before Manually Changing Anything #

When a payment problem occurs, use this order:

1. Verify whether the transaction actually occurred.
2. Check the transaction in Square when applicable.
3. Verify the correct vendor and application.
4. Review VendorHearth’s payment record.
5. Check the Square environment.
6. Verify Square credentials.
7. Check the webhook configuration.
8. Verify the Signature Key.
9. Review System Readiness.
10. Only use a manual payment record when it accurately represents how the payment was received.

This approach helps prevent duplicate or inaccurate payment records.

Next Step #

Continue to Season Passes to learn how VendorHearth manages multi-event vendor passes, payments, automatic event assignment, and capacity checks.