Stripe - Setting up Webhook and Test/Public Keys

To get started, first, you must set up the integration by adding your Stripe keys and generating the Webhook URL.

Test/Publish Keys

You can retrieve the Test/Publishable Key and Secret Key from the > Stripe Dashboard > Developers > API Keys. Copy the keys and add them within the Stripe plugin settings ( Ultimate Member > Settings > Extensions > Stripe )

Note: We recommend that you use a  Restricted Key for live sites and a  Secret Key for local or staging sites for testing purposes. More details can be found in this article.
  • Restricted Key for live sites 
  • Test Publishable Key  for the sandbox mode
  • Live Publishable Key for live mode

Restricted Key Settings

We recommend using the restricted key instead of the standard secret key because the restricted key offers greater security than the secret key. To set your Restricted Key, navigate to Stripe Dashboard >Developers >Api Key >Restricted Key and click the +Edit or +Create Restricted Key button.

Enter a key name look for the resource types listed below in the API Keys and configure the necessary API permissions:
Resource Type Permissions Resources
Customers Write Core resources
Tokens Write  Core/Issuing resources
Checkout Sessions Write  Checkout resources
Credit notes Read Billing resources
Customer Portal Write Billing resources
Prices Read Billing resources
Subscriptions Read Billing resources
Webhook Endpoints Write Webhook resources

Once you're done setting up the restricted key, click the  "Create Key" button, at the bottom right to save your settings.

Webhook

Stripe uses webhooks to communicate with your site. It provides information such as the status of the payment or subscription and is used to update the user's role based on subscription events from Stripe's side of things. This also updates the price and product details on your site when you change them on your stripe.com account.

When you check/uncheck the "Sandbox/Test Mode", you will notice the fields' labels are changing. When checked, the fields will be in test mode, if it is unchecked it means that it is in live mode.

In the Stripe settings, you'll find a webhook endpoint ready for you to copy and paste into your Stripe.com account. When you connect with Stripe, it automatically generates the Webhook URL based on the current domain of your site and adds the event hooks to the Webhook settings on your Stripe account. More details are listed below:

  • Head to Ultimate Member > Settings > Extensions> Stripe. Beside the Webhook Endpoints section is where you can copy your Webhook endpoint URL or when you have added the API Keys, Press on the "Connect with stripe" button, and your Webhook endpoint will be added instantly to your Stripe account settings.

  • When you try to click on the "Connect with Stripe" button, it should validate the Publishable key and Live Restricted or Secret Key. It will show an error message when they are invalid. 

  • If the connection is successful, the "Disconnect Stripe Account" and "Import Prices from your Stripe Account" buttons should appear.
  • If you are trying to connect with Stripe and have installed the Stripe extension on your localhost or own computer while using a local domain, you may encounter an error (as shown in the image below). To receive the payload or events from Stripe.com events transactions, your site's Webhook URL must be publicly accessible. It's important to note that even if you encounter this webhook creation error, you can still import pricing locally.
  • Afterward, navigate to your Stripe Dashboard, go to 'Developers', and access the Webhook Settings. Ensure that the webhook URL has been added to the webhook endpoint. Please keep in mind that there might be a delay before it appears, so it's best to wait a few seconds or try to reload the Stripe page.

  • To view the events, click the webhook endpoint URL. When you click on the Connect with Stripe button from the previous step above, it auto-generates the following event hooks(17):
    • charge.expired
    • charge.failed
    • charge.pending
    • charge.refunded
    • charge.succeeded
    • checkout.session.completed
    • checkout.session.expired
    • customer.created
    • customer.deleted
    • customer.subscription.updated
    • customer.subscription.created
    • customer.subscription.deleted
    • customer.subscription.pending_update_expired
    • customer.subscription.updated
    • payment_intent.payment_failed
    • price.deleted
    • price.updated
    • product.updated
  • If you encounter an error on the site, the webhook may trigger retries after an hour. If you need an immediate trigger, click the "Resend" button in the webhook settings by accessing the webhook URL through Stripe Dashboard>Developers>Webhooks>Hosted Endpoints>Webhook URL.

  • Depending on which you set up first, you can repeat this process for your live Webhook Secret or vice versa.

Need Help? Encountering Issues?

If you encounter any issues with setting up your Stripe integration, such as problems with restricted keys, webhook failures, or permission errors, we recommend checking out our Stripe Extension Common Issues document. This resource provides detailed troubleshooting steps and solutions for common problems. You can access the Stripe Extension Common Issues document here.

NEXT: Setting up Stripe Success and Cancel Payment Pages