Reference

Going live

The switch from test to live, and the checks worth making first.

Going live is a key change, not a code change. If your integration works in test mode, it works in live mode; what changes is that mistakes now cost real money, so this page is mostly about the checks worth making first.

The switch

1. 1

   The business connects live provider keys

   In Providers → Add a provider, the same provider again with Live keys. Test and live are separate connections and both can be connected at once. Harbour shows the live webhook URL to paste into the provider dashboard; it is a different URL from the test one.

2. 2

   Create live Harbour keys

   Settings → Developers, mode Live. This needs a confirmed email address on the account. The secret is shown once.

3. 3

   Add a live webhook endpoint

   Point it at your production URL, mode Live, and copy its own whsec_…. Do not reuse the test endpoint's secret: they are different endpoints with different secrets.

4. 4

   Deploy the environment, not the code

   # staging
   HARBOUR_SECRET_KEY=hb_sk_test_…
   HARBOUR_WEBHOOK_SECRET=whsec_…            # the test endpoint's secret
   
   # production
   HARBOUR_SECRET_KEY=hb_sk_live_…
   HARBOUR_WEBHOOK_SECRET=whsec_…            # a different endpoint, a different secret

5. 5

   Make one real payment

   Buy something small from the real site with a real card, confirm the order is fulfilled by the webhook, then refund it from the dashboard. It costs the provider's fee and it is the only test that proves the live path.

The checklist

• Production uses hb_sk_live_; staging uses hb_sk_test_. Nothing shares a key.
• The live webhook endpoint is HTTPS, reachable from the internet, and answers 2xx in well under ten seconds.
• Webhook handling is idempotent on the event id, and verified before anything else happens.
• return_url is HTTPS and belongs to you.
• The public key's allowed origins list your real domains, if you use harbour.js.
• Secrets are in the environment, not the repository, and do not appear in logs or error pages.
• Someone who is not the developer can reach the dashboard: refunds need an Owner to approve them.
• Test keys that were only ever for development are revoked when you no longer need them.
• Your error path is honest: a provider_unavailable should tell the customer to try again, not show a stack trace.

<?php

// a cheap guard against the classic Friday-evening mistake
if (app()->isProduction() && Harbour::client()->isTestMode()) {
    throw new RuntimeException('Production is configured with a Harbour test key.');
}

The first live day

• Watch Providers for "webhook quiet": it means Harbour has stopped hearing from a provider and is polling to keep the feed right. It is usually a webhook URL missing from the provider dashboard.
• Watch your own webhook logs for non-2xx answers. Harbour retries for 24 hours, so a bad hour is recoverable — but only if you notice.
• Check the settlement calendar after the first payout lands, and that the amount matches the bank.
• Turn on the alerts the business wants in Settings → Notifications: failed payments, settlements landing short, a provider going quiet.