Take payments

Checkout in the browser and in apps

harbour.js for a popup checkout, a no-code Pay button and Harbour Apps widgets, and the React Native and Flutter helpers for apps.

harbour.js opens the same hosted checkout in a popup, so the customer never leaves your page. It is served by Harbour, not by the SDK, and it takes a public key. Card details are still entered on the provider's own page: the popup hands off to them.

With a public key

HTML
<script src="https://pay.harbour.africa/v1/harbour.js"></script>
<script>
  document.getElementById('pay').addEventListener('click', function () {
    Harbour.checkout({
      key: 'hb_pk_live_your_public_key',
      amount: 1200000,                      // kobo
      email: 'funke@example.ng',
      reference: 'order-1043',              // your reference, optional
      onSuccess: function (result) {
        // result.reference === "HB-88413": hand it to your server and verify there
        fetch('/orders/1043/confirm', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ reference: result.reference })
        }).then(function () { window.location = '/thanks'; });
      },
      onClose: function () { /* the customer closed the popup */ },
      onError: function (err) { console.error(err.message); }
    });
  });
</script>

Restrict the public key to your own domains in Settings → Developers so it cannot be used from someone else's site.

Your confirm endpoint
// POST /orders/1043/confirm — the browser is not a source of truth
const checkout = await harbour.charges.verify(req.body.reference);

if (checkout.status === 'succeeded' && checkout.amount_kobo === order.totalKobo) {
  await order.markPaid();
}

With a checkout token

If you would rather create the charge on your server (so the amount is never in the page), pass the checkout token instead of the public key. Checkout::inlinePayload() returns exactly what harbour.js needs:

PHP
SDK language
Any language can call the API today
<?php $payload = $checkout->inlinePayload(); ?>
<script src="https://pay.harbour.africa/v1/harbour.js"></script>
<script>
  Harbour.checkout(Object.assign(
    <?= json_encode($payload, JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT) ?>,
    { onSuccess: confirmOnServer }
  ));
</script>

The payload carries token, amount, email and reference — no key, and nothing a customer can usefully edit.

When popups are blocked

harbour.js falls back to a full-page redirect on its own. The customer comes back to the charge's return_url with ?reference=HB-…&status=succeeded, so your return page must handle that case too. With the public-key form, set a return URL by creating the charge server side first, or handle onClose by reloading the order page.

A Pay button with no code

Put your public key on the script tag once, and any element with data-harbour="checkout" becomes a Pay button. The amount is in kobo (or cents). Leave out data-email and Harbour's own page asks the customer for it, then goes straight to the provider.

HTML
<script src="https://pay.harbour.africa/v1/harbour.js" data-key="hb_pk_live_your_public_key" async></script>

<button data-harbour="checkout" data-amount="250000" data-currency="NGN"
        data-description="Order 1043" data-reference="order-1043">Pay ₦2,500</button>

The amount, currency, description and reference are signed when the page opens, so the customer cannot change them. Other attributes: data-email, data-name, data-phone and data-return-url. The same page works as a plain link, without the script: https://pay.harbour.africa/start?key=hb_pk_…&amount=250000&description=Order%201043. In live mode it only opens from the websites listed on the key. The dashboard writes all of this for you, with your key, in Apps → Harbour Checkout → Embed.

Widgets from Harbour Apps

Apps that appear on your website, such as Harbour Invoice, StoreFront and Tickets, use the same script. Each widget is an element with data-harbour and the item's id. It loads in a frame from pay.harbour.africa, so customer and payment details never touch your page, and it resizes itself to fit.

HTML
<script src="https://pay.harbour.africa/v1/harbour.js" data-key="hb_pk_live_your_public_key" async></script>

<div data-harbour="invoice" data-invoice="inv_…">
  <a href="https://pay.harbour.africa/…">Pay this invoice</a>   <!-- shown without JavaScript -->
</div>
<div data-harbour="store" data-collection="col_…"></div>
<div data-harbour="buy" data-product="prd_…"></div>
<div data-harbour="tickets" data-event="evt_…"></div>

Leave a plain link inside the element: harbour.js replaces it with the widget, and visitors without JavaScript still get the link. A widget whose app is not switched on (or not live yet) shows a short notice instead of breaking your page.

Events and single-page apps

harbour.js finds widgets added after the page loads, so React, Vue and similar apps work without extra code. To mount one yourself, call Harbour.mount(element). To react to what happens, listen with Harbour.on, or for the DOM event on the element (harbour:paid, harbour:closed, harbour:ready, harbour:error):

JavaScript
Harbour.on('paid', function (e) {
  // e.widget: "checkout", "invoice", ...; e.reference: "HB-88413"
  fetch('/orders/confirm', { method: 'POST', body: JSON.stringify({ reference: e.reference }) });
});
Harbour.on('closed', function (e) { /* the customer closed the payment window */ });

document.querySelector('#pay').addEventListener('harbour:paid', function (ev) {
  console.log(ev.detail.reference);
});

As with onSuccess, a paid event is a signal to check, not proof: confirm on your server or by webhook.

Versions and integrity

/v1/harbour.js always serves the latest compatible release, and /harbour.js is the same file. If your site only loads scripts with a checked hash, use a pinned release such as /v1.1.0/harbour.js with its integrity value from the Embed tab. A pinned release never changes, so you update it yourself when a new one is announced. A future incompatible version would be /v2, with /v1 kept running for at least twelve months.

Your Content-Security-Policy

If your website sets a Content-Security-Policy, allow Harbour in three places:

TEXT
script-src  'self' https://pay.harbour.africa
frame-src   https://pay.harbour.africa
connect-src 'self' https://pay.harbour.africa

Inside a mobile app

Do not embed the checkout in a WebView: providers reject some card flows there, and 3-D Secure can break. Open checkout_url in the system browser component instead — Chrome Custom Tabs on Android, SFSafariViewController on iOS — with return_url set to your deep link.

// your server, when the app asks to start a payment
const checkout = await harbour.charges.create({
  amountKobo: order.totalKobo,
  customer: user.email,
  reference: order.reference,
  returnUrl: 'myapp://harbour/return',          // your app's deep link
});

res.json({
  checkout_url: checkout.checkout_url,          // open this in a Custom Tab / SFSafariViewController
  reference: checkout.reference,
});

Harbour appends ?reference= and &status= to the deep link. When your app is woken by it, call your own server to verify; the app never talks to Harbour with a secret key.

React Native and Expo

@nordaxiz/harbour-react-native does the opening and the reading for you. It uses expo-web-browser when it is installed; in a bare React Native app, pass your own opener (for example react-native-inappbrowser-reborn's openAuth).

JavaScript
import { openCheckout } from '@nordaxiz/harbour-react-native';   // npm install, plus npx expo install expo-web-browser

// checkoutUrl comes from your server: POST /v1/charges with return_url "myapp://harbour/return"
const result = await openCheckout({ checkoutUrl, returnUrl: 'myapp://harbour/return' });

if (result.outcome === 'returned') {
  await api.confirmOrder(result.reference);   // your server verifies with GET /v1/charges/{reference}
}

For an app without its own server, create the checkout with a public key:

JavaScript
import { createCheckout } from '@nordaxiz/harbour-react-native';

// apps without a server: a PUBLIC key can only create checkouts; a secret key is refused outright
const checkout = await createCheckout({
  publicKey: 'hb_pk_live_…', amountKobo: 1_200_000, email: 'funke@example.ng', returnUrl: 'myapp://harbour/return',
});

Flutter

The harbour_checkout package is pure Dart: it reads the result from the deep link, checks a checkout URL, and creates checkouts with a public key. Open the checkout with any in-app browser that reports the redirect, such as flutter_web_auth_2:

Dart
import 'package:flutter_web_auth_2/flutter_web_auth_2.dart';
import 'package:harbour_checkout/harbour_checkout.dart';

final redirect = await FlutterWebAuth2.authenticate(url: checkoutUrl, callbackUrlScheme: 'myapp');
final result = HarbourReturn.fromUrl(redirect);     // HB-... and the status, or null
if (result != null) {
  await api.confirmOrder(result.reference);         // confirm on your server
}
  • A return_url for an app must have the scheme://host form, such as myapp://harbour/return or com.okafor.shop://paid, and the scheme must be registered by your app.
  • Harbour refuses schemes that run code, read files or open other apps: javascript:, data:, file:, intent: and similar. Web return addresses must be https://.
  • The status in the deep link is for the screen only. Fulfil an order only after your server has verified the charge or received the charge.succeeded webhook.