Stripe payment provider setup

Connect your company’s Stripe account to its TractorHQ website without emailing or texting API keys. You enter the credentials directly in your own HQ account, then your TractorHQ representative reviews the connection before live payments are enabled.

This guide uses the manual restricted-key setup. The Connect Stripe button starts a separate onboarding flow; you do not need to click it to follow these steps.

About the screenshots

The screenshots show qa.tractorhq.com, company Tractor HQ, with Stripe Disabled and credentials empty. Use your own company’s account and website for the actual setup. The orange Database neutralized for testing banner identifies QA; it is not a payment configuration step. No Stripe account was connected and no payments or webhooks were created for these screenshots.

Before you start

You need:

• Access to the Stripe account that belongs to the company receiving payments, with permission to manage API keys.
• An HQ user with the Payment Provider Manager level (or an HQ administrator) who can access Payment Providers and edit Stripe credentials. Developer mode exposes technical options; it does not grant these permissions. See Payment provider access: roles and structure for who grants the level.
• The correct company selected in HQ and confirmation of the intended website/domain.
• A TractorHQ representative available to review the connection and finish the payment configuration.

Keep QA separate from live payments

Never enter live Stripe keys into QA for a demonstration. For an authorized payment test, use keys from the same Stripe sandbox/test environment and set the HQ provider to Test Mode. Use live keys only on the intended production website, with the final activation coordinated by your representative.

1. Prepare the company’s Stripe account

1. Sign in at stripe.com or create a business account.
2. Check that you are viewing the correct business/account, especially if you manage several companies.
3. Complete Stripe’s required business information, identity verification, contact details, and payout bank account.
4. Before going live, resolve any Stripe activation requirements or restrictions on accepting payments.

Expected result: you have access to the company’s Stripe account and know whether you are configuring a sandbox/test environment or live payments.

2. Create a restricted API key

1. In the Stripe Dashboard, open Developers → API keys and choose Create restricted key. Dashboard navigation can vary; use Stripe’s API keys page if needed.
2. Name the key TractorHQ so you can identify its purpose later. For a Headland website, use Headland.
3. Grant Write access to these resources, as specified in the Headland / TractorHQ client setup guide:
   • Payment Intents
   • Setup Intents
   • Payment Methods
   • Customers
   • Charges / Refunds — if Stripe lists these separately, include both.
   • Webhook Endpoints
4. If you plan to offer Apple Pay, also grant Write access to Apple Pay Domains.
5. Leave unrelated permissions at None / no access. Do not grant unrestricted access to work around an error; ask your representative to identify the missing permission.
6. Create the key and keep it available securely for entry into HQ. Also locate the account’s Publishable key.

Use both keys from the same Stripe account and environment:

• Live production setup: publishable key starts with pk_live_; restricted key starts with rk_live_.
• Sandbox/test setup: publishable key starts with pk_test_; restricted key starts with rk_test_.

These are prefixes, not usable example credentials. A restricted key is a secret even though its permissions are limited. Do not send it to your representative, put it in a support ticket, or include it in a screenshot.

Expected result: you have a matching publishable key and restricted key for the intended environment, with only the required permissions.

3. Open HQ in developer mode

1. Sign in to your company’s HQ website.
2. Open /hq?debug=1 on that same hostname. For the QA example, the address is https://qa.tractorhq.com/hq?debug=1.
3. If the address already has a query string, append &debug=1 instead of adding a second ?.
4. Check the company selector in the top bar. Select the company you are configuring; the screenshots use Tractor HQ.

Expected result: you are signed in to the correct HQ environment with the intended company active.

4. Open that company’s Stripe provider

1. Open the Website application and choose Configuration → Payment Providers. If you have the Payment Provider Manager level and no Website access, open Invoicing → Configuration → Online Payments → Payment Providers instead.
2. Both menus open the same list of providers.
3. Find Stripe and confirm its Company matches the intended company.
4. Open the existing Stripe record. Do not create a second provider merely because it is Disabled.

On the Stripe form, check Company again. Check Website with your representative if your company has multiple sites. The blank Website field in the QA example is not an instruction to clear your own website assignment.

Do not enable payments yet

Keep the provider Disabled while entering production credentials and waiting for review. The Published label is separate from State: it does not prove that Stripe is configured or that live payments work. Do not change publication or other settings just to match a screenshot.

5. Enter the credentials and save

Open the Credentials tab and enter:

• Publishable Key: your matching Stripe publishable key (pk_live_ for production, or pk_test_ for a sandbox/test setup).
• Secret Key: your restricted key (rk_live_ for production, or rk_test_ for a sandbox/test setup). The HQ field is labeled Secret Key, even when you are using a restricted key. You do not need to replace it with an unrestricted sk_ key.

Use Save (the cloud/check icon, accessible as Save manually in the QA interface), then reopen the record if needed to confirm the form saved without errors. Do not reveal the password-style field for a screenshot.

The Payment Provider Manager sees the same fields as an administrator. The next screenshot shows the administrator view for the Tractor HQ company.

The screenshot intentionally contains no keys. Connect Stripe is visible because this QA record has no credentials; continue with manual entry for this guide.

Expected result: both credentials have been saved on the correct company’s provider. Saving credentials alone does not verify a payment or complete the webhook setup.

6. Generate the webhook

A webhook lets Stripe notify HQ about payment events; HQ uses the Webhook Signing Secret to verify those notifications.

1. After saving the credentials, look for Generate your webhook in the Credentials tab, next to Webhook Signing Secret.
2. Click it once and check the resulting success or error notification.
3. Reopen the provider and confirm that Webhook Signing Secret is populated. Keep its value hidden.
4. Ask your representative to verify in Stripe that the webhook destination points to the intended public HTTPS website, not a QA or another company’s hostname, and that it uses the matching Stripe environment.

Why the button is not in the screenshot

Generate your webhook is hidden when Secret Key is empty, as in the QA screenshot. It is also hidden when a Webhook Signing Secret is already present. If a signing secret already exists, ask your representative to verify the existing destination rather than clearing it or creating duplicates. The Payment Provider Manager level (or administrator access) is required; developer mode alone is not enough.

Do not paste an API key into Webhook Signing Secret. That field holds a separate secret associated with the webhook endpoint, not your publishable or restricted API key.

Expected result: the signing secret is stored in HQ and the webhook destination has been checked for the correct site and Stripe environment. Its presence alone does not prove event delivery works.

7. Contact your TractorHQ representative

Tell your representative that the credentials have been saved and the webhook has been generated. Share only the company name, website/domain, environment (test or live), and any error message with secrets removed. Do not send keys or screenshots that expose them.

Your representative will review the connection and finish the payment configuration, including:

• The correct company, website, Stripe account, and key environment.
• The payment journal, available payment methods, and any currency, country, or amount restrictions.
• Successful webhook delivery and the corresponding payment status in HQ.
• A controlled payment test in the agreed environment, including refund behavior if applicable.
• Production activation only after the agreed checks are complete.

The Configuration tab contains options such as Allow Saving Payment Methods, Capture Amount Manually, Allow Express Checkout, and Payment Journal. Do not copy QA defaults without discussing your company’s requirements.

For Apple Pay, the representative should also review Allow Express Checkout and Enable Apple Pay on this tab and verify the intended live domain. Granting the Apple Pay key permission alone does not finish Apple Pay activation; do not enter live credentials into QA to try the button.

Expected result: your representative confirms the connection is ready before your production provider is set to Enabled. Do not use a real customer card for a QA demonstration.

Troubleshooting

• Payment Providers or credential fields are missing: check the active company, enable developer mode, and ask your Solutions Manager to give you the Payment Provider Manager level in Online Payments. Do not create another account or provider as a workaround.
• Generate your webhook is missing: save the restricted key first and check whether a signing secret already exists. If both conditions are correct, ask your Solutions Manager to check that you have the Payment Provider Manager level.
• Stripe reports insufficient permissions: review the restricted-key permissions above and have your representative inspect the specific Stripe error. Do not switch to an unrestricted key by default.
• Authentication or mode error: check for accidental whitespace and verify that both keys belong to the same Stripe account and environment. Re-enter them privately; never send their values to support.
• Webhook fails or payment status does not update: have your representative check the actual webhook destination, event delivery/error details, signing secret, and matching test/live environment. Do not repeatedly regenerate endpoints.
• Stripe is not offered at checkout: after setup is approved, have your representative check State, publication, website assignment, enabled payment methods, availability restrictions, and the order’s amount/currency. A successful save does not guarantee checkout availability.

Completion checklist

• Correct HQ environment, company, and intended website confirmed.
• Stripe business account ready for the intended payment environment.
• Restricted key has the required permissions and no unrelated access.
• Matching publishable and restricted keys saved in the correct fields.
• Webhook signing secret stored and destination verified.
• TractorHQ representative notified without disclosing secrets.
• Representative completes payment/webhook testing and approves activation.

References

This guide adapts the Headland / TractorHQ — Stripe Payment Setup client handout (restricted-key workflow). See also:

• Stripe API keys: types, security, and sandbox versus live mode
• Odoo 18 Stripe provider: manual credential input, webhook, and Apple Pay

The client handout specifies a restricted key; general Odoo documentation also describes standard secret keys. Follow the restricted-key workflow here and have your representative confirm any additional permissions needed for your enabled features.