Setting up a payment provider

Where

Settings → Payment Gateways

Plan

All plans

Permission

Payments → Gateway Config

Nothing in the Payments menu can collect money until a provider is configured here. Confusingly, this screen is not in the Payments menu — it lives in Settings.

Three providers are supported: Paystack, Hubtel and PaySwitch (the theTeller API).

No plan is required

Unlike the Payments menu, this screen needs only the permission. There is no plan gate on it at all.

Before you start

Have your provider’s dashboard open. You will be copying keys out of it.

• Paystack — your secret key, from Settings → API Keys & Webhooks. It begins sk_live_ or sk_test_.
• Hubtel — your API client ID and client secret, and your merchant account number.
• PaySwitch — your API user and API key, and your merchant ID.

Adding a provider

1. Go to Settings, choose Payment Gateways, then click the Payment Gateways row inside it. (Yes — twice.)
2. Click New gateway.
3. Choose the Gateway — Paystack, Hubtel or PaySwitch. This can never be changed afterwards.
4. Type a Display name, any label that helps you recognise it.
5. Leave Purpose on Merchant collection. Also permanent — and see the warning about Billing below.
6. Leave Enabled on Yes.
7. Set Priority only if you configure more than one provider: the enabled one with the lowest number is your default (see Priority decides the default provider below).
8. Under Credentials, fill in the boxes for your provider:
   • Paystack — Secret key, and optionally Public key.
   • Hubtel — Username, Password, Merchant ID.
   • PaySwitch — Username, Password, Merchant ID, and optionally Network (a fallback only — see below).
9. Enter a Webhook secret if your provider issues one. Read the section below first — it does less than it sounds like.
10. Leave Raw config (advanced) empty.
11. Click save. You get “Gateway saved”.

The heading warns you correctly: “Your provider keys are encrypted at rest and never shown again after saving.”

There is no way to test that your keys are right

No test button, no verify, nothing. Saving only proves the form was filled in.

The Credentials column then shows a green Set badge — which means a value is stored, not a working value. A completely wrong key shows Set. You find out when a real customer’s payment fails.

Make the first payment yourself, for a small amount, before letting customers near it.

Nothing checks that you filled in the right boxes

The form accepts any one credential box being filled. A Paystack entry saved with only the public key, or a Hubtel entry with only a merchant ID, saves happily and shows Set.

Check every box for your provider before saving.

The webhook URL

Your provider needs to be told where to notify SaleSprint when a payment changes.

Each gateway entry shows a read-only Webhook URL. It has this shape:

https://<SaleSprint API address>/api/v1/webhooks/payments/<provider>

where <provider> is exactly paystack, hubtel or payswitch. Copy it into your provider’s dashboard: Paystack under Settings → API Keys & Webhooks, and the equivalent callback or webhook setting for Hubtel and PaySwitch.

• No workspace ID is needed. SaleSprint works out which workspace and which payment a notification belongs to from the payment reference itself. Older instructions that ended the URL with ?tenant=… still work, but the extra part is no longer needed.
• One URL per provider is enough. The same address serves every payment.

The Webhook URL is blank

That means your SaleSprint operator has not set the public API address for this installation (PUBLIC_API_BASE_URL). Ask them to set it, or ask for the URL.

A notification is only a nudge

SaleSprint never marks a payment as paid just because a notification says so. Every notification makes SaleSprint ask the provider directly about that payment, and only the provider’s own answer counts. A fake or replayed notification cannot invent money.

The amount and currency the provider reports must also match the request exactly. If they do not — for example the customer paid less — the request is not marked paid and nothing reaches your balance. It is set to Under review instead, with the reason recorded on its transaction.

When a notification never arrives

Payments are not lost. SaleSprint checks every open payment with the provider on its own: a few minutes after the payment is started, then every few minutes for up to a week. A customer who returns to the payment page after paying also triggers a check, so the page usually turns to paid within seconds. A notification that arrived while the payment was still pending is re-checked automatically afterwards.

Payments that are never completed are cancelled once they expire (after SaleSprint has confirmed with the provider that nothing was paid).

The Webhook secret box

What it does depends on which provider you chose.

Provider	What the Webhook secret does
Paystack	Nothing. Paystack signs every notification with your secret key, and SaleSprint checks that signature. Leave the box blank.
Hubtel	The signing key. Notifications must carry a matching HMAC-SHA256 signature of their content.
PaySwitch	Same as Hubtel.

Only enter a secret your provider actually signs with

On Hubtel or PaySwitch, once a secret is stored every notification without a matching signature is refused. If your provider is not set up to sign notifications with that same key, they will all be rejected. Payments still complete, but only through SaleSprint’s own checks, so a little later.

With no secret stored, notifications are accepted without a signature. That is safe: as explained above, a notification only makes SaleSprint check with the provider, so a fake one cannot mark anything paid.

A webhook secret can be replaced but never removed

Clearing the box keeps whatever is stored. The same is true of Notes.

Which configuration is actually in use

A banner above the table tells you one of:

• “Your own Paystack configuration is currently active.”
• “Currently using the platform default gateway (Paystack).”

The second means you have not set anything up and SaleSprint is falling back to a provider your operator configured.

No banner at all means nothing is configured

If neither your own nor a platform default resolves, the banner simply does not appear. There is no warning that payment collection will fail. An empty space where the banner should be is the only sign.

The list

Columns are Display name, Gateway, Purpose, Priority, Enabled and Credentials. Row actions are Edit and Delete.

Deleting warns you: “This removes your override and reverts to the platform default.” If there is no platform default, collection stops working instead — nothing says so.

Changing keys later

Re-typing one key wipes the others

On the edit form every credential box is blank, with the helper “Configured — leave blank to keep the current value.” That is true per box, but misleading overall: typing into any one box replaces the whole stored set, and the boxes you left blank are lost.

When rotating a key, re-enter every credential for that provider, not just the one that changed.

Gateway and Purpose cannot be changed at all. A mistake in either means deleting the entry and creating it again.

Two things to avoid

Do not choose Purpose = Billing

It is offered in the dropdown, it saves, and it shows a green Set badge — and it is never used. Billing your SaleSprint subscription uses your operator’s own provider, not yours. Always leave it on Merchant collection.

The PaySwitch Network box is only a fallback

For a mobile-money payment SaleSprint uses the network the customer picked (MTN, Telecel or AirtelTigo) or, if they did not pick one, the network their phone number belongs to. The Network credential is used only when neither is known, and when that is blank too, MTN is assumed.

Priority decides the default provider

When a payment does not name a provider — the online shop, a payment link, a request with the Gateway left blank — SaleSprint uses your default: the enabled provider with the lowest Priority number (ties go alphabetically). If your operator has routed a channel to a specific provider (for example card to one, mobile money to another), that routing wins.

Related

• Payments overview
• Collecting payments
• Getting paid online — pay links on invoices, and what the customer sees
• Troubleshooting invoices and online payments