Your Keys, Your Till
Card and mobile money collection run on your own provider credentials, so the money lands in your account without passing through ours. That is a deliberate architectural choice with consequences for reconciliation, for risk, and for what happens when a key is wrong.
There are two ways to let a business take card payments. In one, the money goes to them. In the other, it goes to the software vendor and then to them.
Our take
Holding merchant funds is a large and profitable business and it is not this one. Every card and mobile money collection here is initiated with your own provider credentials against your own merchant account, so the settlement is between you and your provider and we are never in the path of the money. That means we cannot delay your settlement, cannot net fees out of it, and cannot become a party to a chargeback — and equally, we cannot help you with any of those things, because the relationship is yours. For most businesses that is the right trade by a wide margin. The cost is that you carry the provider relationship: the onboarding, the keys, the environment, and the discipline of noticing when a credential stops working.
What "your own credentials" means concretely
Each organisation stores its own configuration for each rail. A card transaction is initialised against your secret key; funds settle to your account. A mobile money prompt is raised with your consumer key and secret, and the money lands in your till. Neither call touches the platform's own payment configuration, which exists for a completely different purpose — collecting subscription fees from you — and is a separate set of objects entirely.
- The keys are per organisation, so two businesses on the same installation collect into two different merchant accounts and neither can reach the other's.
- The environment is part of the configuration, so a sandbox setup and a production one are separate credential sets that cannot be confused for each other.
- Access tokens are cached per organisation and per environment, for just under an hour, and can be forced fresh when a credential changes.
- Both clients fail soft, returning a clean refusal rather than throwing, so an incomplete configuration produces a message a cashier can read instead of an error page.
Incomplete configuration is refused before anything is attempted
A card transaction with an incomplete configuration returns "Paystack is not fully configured for this business" without a network call. A mobile money token request with an empty key or secret returns nothing, immediately. This matters at a till, where the difference between a clear refusal and a thirty-second timeout is the difference between a cashier switching to cash and a queue forming.
The subunit, and why it is worth naming
Card providers take amounts in the smallest unit of the currency — cents, not units. A charge of 1,450 shillings is submitted as 145,000. That conversion happens once, in one place, and it is the kind of detail that is completely invisible when right and produces a hundredfold error when wrong.
It is also why the currency is fixed rather than derived on this path: the collection rails as wired today submit in shillings. An organisation trading in another currency is a conversation about extending the rail rather than a setting, because the subunit rule and the provider's supported currencies both have to be right together.
A hundredfold error is not a rounding difference. It is a different transaction.
The two rails fail differently on the way back
Initiating a payment is the easy half. The interesting half is the callback that tells you it succeeded, and the two providers are not equivalent there — which is why they are not treated equivalently.
| Card | Mobile money | |
|---|---|---|
| Does the provider sign its callbacks? | Yes, with a keyed hash we verify | No |
| So what authenticates the callback? | The signature, checked in constant time | The source address, and nothing else |
| Address filtering posture | A second lock — an empty list allows, because the signature is the primary check | The only lock — an empty list refuses, and the published ranges ship as the default |
That asymmetry is deliberate and it is worth knowing if you ever consider clearing an address list to "switch filtering off". On the card rail that is a reduction in defence in depth. On the mobile money rail it would be switching off the only authentication on a public endpoint that moves money — so the system refuses to run that way.
More rails, same posture
The pattern is settled: credentials per organisation, funds to your account, a clean refusal when configuration is incomplete, and callback authentication matched to what the provider actually offers.
Additional acquirers and gateways
A rail wired the same way for whichever provider your market uses, with its own credential set and its own callback authentication.
Collection in another currency
The subunit rule and the provider's supported currency list handled together, so a business trading outside shillings can collect on the same rails.
A credential health check
A scheduled probe confirming each configured rail still authenticates, so an expired key is found before a customer is standing at a counter.
We publish scope, not dates.
Scope a payment railFive questions to ask any system that takes payments for you
Whose merchant account does the money land in?
A good answer sounds like
Yours, named.
What ours actually is
Yours. Every collection call uses your organisation's own credentials and settles to your account.
Does the vendor ever hold my funds?
A good answer sounds like
A straight no, or a licence.
What ours actually is
A straight no. We are not in the settlement path, which also means we cannot delay it or net anything out of it.
What authenticates the payment callback?
A good answer sounds like
A signature, or an address list, and which.
What ours actually is
A keyed signature checked in constant time on the card rail; the source address on the mobile money rail, because that provider signs nothing.
What happens if a key is wrong?
A good answer sounds like
A clean refusal.
What ours actually is
A refusal before any network call, with a message a cashier can act on rather than a timeout.
Are sandbox and production separable?
A good answer sounds like
Yes, by configuration.
What ours actually is
Yes. The environment is part of the credential set and tokens are cached separately per environment.
What AWRA OpsHub does today
- Card collection initiated with your organisation's own provider credentials, settling to your own merchant account, never touching the platform's subscription configuration.
- Mobile money collection raised with your own consumer credentials, with the money landing in your own till.
- An environment stored alongside each credential set, so sandbox and production are separate configurations with separately cached access tokens.
- Access tokens cached per organisation and environment for just under an hour, with a forced-refresh path for when a credential changes.
- A clean refusal before any network call when a configuration is incomplete, rather than a timeout at the counter.
- Amounts converted to the provider's smallest currency unit in one place, so the conversion is defined once rather than at each call site.
- Keyed signature verification on the card provider's callbacks, compared in constant time.
- Source address filtering that fails closed on the mobile money rail, because that provider signs nothing and the address is the only authentication — with the published ranges shipped as the default.
More we can add to your workspace
- A scheduled credential health check, confirming each configured rail still authenticates so an expired key is found before a customer is at the counter.
- Collection in currencies other than shillings on these rails, with the subunit rule and the provider's supported list handled together.
- Additional acquirers and gateways for markets these two rails do not cover.
- A settlement reconciliation feed, matching the provider's payout report against the transactions that produced it.
- A retry with a fresh token on an authentication failure, so a token that expired mid-transaction does not surface as a payment failure.
- A per-rail dashboard showing initiated, completed and abandoned transactions, so an intermittent failure is visible as a rate rather than as individual complaints.
Where we point you to a specialist
- We will not hold your customers' money. Sitting in the settlement path would make us a party to your chargebacks, your refunds and your float, and it is a regulated activity in most of the markets this runs in. Your provider relationship stays yours, which is the reason your settlement timing is not ours to affect.
- Merchant onboarding, fees, settlement timing and dispute handling belong to your provider, and we will point you to them rather than answering on their behalf. What we own is that the call is made correctly with your credentials and that the callback is authenticated properly.
- We will keep the mobile money callback failing closed when its address list is empty. That endpoint is public, exempt from cross-site protections and moves money, and the source address is the only thing authenticating it — so an empty list has to be a refusal rather than a permission.
A credential health check is the highest-value small piece here: every rail already reports its own configuration completeness, and the difference between finding an expired key on a schedule and finding it at a till is an afternoon of trading.
Check who holds your keys
The question is worth asking of every system that takes money on your behalf, and the answer should be a sentence rather than a paragraph. If it takes a paragraph, the money is going somewhere before it reaches you.
Talk through payment collectionFrequently asked questions
Does the software vendor see or hold our payments?
No. Collections are initiated with your own provider credentials and settle to your own merchant account, and the platform's own payment configuration — which exists to collect subscription fees from you — is a separate set of objects that these paths never touch. The practical consequence is that your settlement timing, your fees and your disputes are between you and your provider.
What happens if we put in the wrong keys?
The rail refuses before making a network call, and the refusal is a readable message rather than an error. That is deliberate: at a till, a clear "not configured" lets a cashier switch to another tender immediately, while a timeout produces a queue and a customer who has been charged or not charged and nobody is sure which.
Can we test with sandbox credentials?
Yes. The environment is stored as part of the credential set and access tokens are cached separately per environment, so a sandbox configuration and a production one cannot be confused for one another. Switching between them is a configuration change rather than a code change.
Why is one rail's address filtering stricter than the other's?
Because one provider signs its callbacks and the other does not. Where a keyed signature is verified on arrival, address filtering is a second lock and an empty list is a reduction in defence rather than an open door. Where nothing is signed, the source address is the only authentication on a public endpoint that moves money, so an empty list has to be treated as a refusal.
Can we collect in a currency other than shillings?
Not on these two rails as wired. The amount conversion to the provider's smallest unit and the provider's own supported currency list have to be correct together, which makes it a scoped extension rather than a setting. It is on the list above and is the most common request from businesses trading across a border.
How would we know if a key stopped working?
Today, when a transaction fails. There is no scheduled probe confirming each configured rail still authenticates, which is the first item on the list above — and the gap between finding an expired credential on a schedule and finding it at a counter is usually a day of trading.
