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
<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.
// 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();
}
<?php
// POST /orders/1043/confirm — the browser is not a source of truth
$checkout = Harbour::verify($request->json('reference'));
if ($checkout->isPaid() && $checkout->amountKobo === $order->total_kobo) {
$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
<?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.
<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.
<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):
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:
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,
});
<?php
// your server, when the app asks to start a payment
$checkout = Harbour::charge($order->total_kobo, $user->email, [
'reference' => $order->reference,
'return_url' => 'myapp://harbour/return', // your app's deep link
]);
return response()->json([
'checkout_url' => $checkout->checkoutUrl, // 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).
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:
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:
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
}
Deep-link rules
- A
return_urlfor an app must have thescheme://hostform, such asmyapp://harbour/returnorcom.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 behttps://. - 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.succeededwebhook.