Inside a Spooray account: the wallet, the sprays, the events

Every gift on Spooray is one ledger entry: a sender, a recipient, an amount, the event it was sprayed at, and even the sound the giver chose as the cash "rained" down. That single record — repeated across birthdays, weddings and graduations, and tied to a wallet that was loaded from a linked bank — is the thing an integrator actually wants. The app takes the West African tradition of spraying money at a celebration and turns it into structured, server-side transactions. Reach those transactions cleanly and you can reconcile an event, build a remittance feature, or sync a giver's history into another product.

The bottom line: this is real money movement, in naira, sitting under a consent regime that Nigeria put on paper before any other African country. So the dependable basis for reaching a user's data is that user's own authorization — and the practical work is mapping the wallet, the spray transfers and the events into something another system can read. For a Nigerian account we'd start from the consent route; for a diaspora account or a quick pilot, we map the app's own traffic and reconcile both against the same wallet ledger.

What sits behind a Spooray account

These are the surfaces the app exposes to its own users, named the way Spooray frames them. An integration normalizes them into a stable schema you control.

Getting to the data, the authorized way

Three routes apply to Spooray. We'd typically combine the first two.

Account-holder consent under Nigerian open banking

Nigeria's CBN framework is built around consent-permissioned sharing of a customer's data with a registered third party. For a Nigerian Spooray user, this is the durable path: a consent token scoped to one account, survivable across app updates, with revocation in the user's hands. Effort sits mostly in the consent and registry plumbing, which we set up with you during onboarding. What's reachable depends on how the underlying funding bank and the app participate, so we scope it per account type rather than promising a single fixed feed.

Authorized protocol analysis of the app's traffic

With a consenting account, we observe the traffic between the app and its servers, map the wallet, ledger, spray, event and schedule calls, and reimplement them as a clean, documented API. This works regardless of where the account sits, including diaspora users outside the open-banking perimeter, and it is how we capture surfaces the consent route doesn't expose — the chosen sound, the social posts. Durability tracks the app's front end, so we re-validate the captured flows as the screens change.

User-consented session access

Lightest of the three: a consenting account hands us an authorized session for a one-off export or a pilot. Good for proving value on real data this week before the fuller consent integration is wired in. We keep the session scoped and never store standing credentials.

For Nigerian accounts we'd lead with the consent route, because the CBN rules are written around it and it does not break when the app ships an update. Where an account falls outside that perimeter, or you need something running before the consent paperwork clears, we map the app's own traffic and reconcile the two against the same wallet ledger so the numbers agree.

What lands in your repo

Each deliverable is tied to Spooray's actual surfaces, not a generic checklist:

• OpenAPI / Swagger spec covering wallet balance and ledger, spray and gift transfers, events, recipients and scheduled gifts — request and response shapes documented field by field.
• Protocol & auth-flow report describing the consent or session token chain as it applies here: how the authorized session is established, how it refreshes, and how a revoked consent surfaces.
• Runnable source for the key endpoints in Python or Node.js — the wallet-ledger pull, the spray-transaction reader, the event-to-spray join, and the scheduled-gift feed.
• Automated tests against recorded fixtures, including the pending-versus-settled states a scheduled spray moves through and the bank-plus-feature fee split.
• Interface documentation a developer can hand to a teammate, with the normalized schema and reconciliation notes.
• Compliance and data-retention guidance: what consent scope you hold, how long to keep records, and how to honor a revocation.

A spray, in code

Illustrative shape — field names are confirmed against the live app during the build, not copied from any vendor document. It shows the core record and how we read a month of wallet history under an authorized session.

# Authorized session: an open-banking consent token (CBN registry flow)
# or a session token from a consenting account. No standing credentials stored.
client = SprayClient(consent_token=CONSENT)   # token scoped to one account

# Wallet ledger for a date range
ledger = client.get("/wallet/ledger", params={
    "from": "2026-05-01",
    "to":   "2026-05-31",
    "page": 1,
})

# A single spray — the core unit, normalized:
# {
#   "id":          "spr_8f2a...",
#   "type":        "spray",
#   "amount":      5000,            # minor units
#   "currency":    "NGN",
#   "sender":      "usr_a1...",
#   "recipient":   "usr_b7...",
#   "event_id":    "evt_2c...",     # the celebration it was sprayed at
#   "sound":       "owambe_horn",   # entertainment metadata
#   "scheduled_at": null,           # set when pre-scheduled
#   "fee":         {"bank": 26.88, "feature": 50.00},
#   "status":      "settled",       # pending | settled | failed
#   "created_at":  "2026-05-18T19:42:07Z"
# }

for tx in ledger["data"]:
    if tx["status"] == "pending":
        watch_until_settled(tx)     # scheduled sprays update in place
    elif tx["status"] == "failed":
        flag_for_review(tx)
    else:
        post_to_books(tx, fee=tx["fee"]["bank"] + tx["fee"]["feature"])
      

The fee object and the event link are the parts most integrations get wrong, so they sit in the snippet on purpose.

Consent, the CBN rules, and the data act

Spooray moves real funds in a market with a written open-banking regime. The Central Bank of Nigeria released its Operational Guidelines for Open Banking in March 2023, per the CBN circular, making Nigeria the first African country with such a framework; the CBN keeps an Open Banking Registry so only registered participants exchange customer-permissioned data. Personal data itself falls under the Nigeria Data Protection Act 2023. There is also a cultural-legal backdrop here: physically spraying naira at parties is restricted under the CBN Act, which is part of why digital spraying exists at all.

For us the practical point is narrow. The reliable basis for touching a user's Spooray data is that user's consent, captured and revocable. We define a consent scope down to the domains a project needs — say the wallet ledger and spray transfers, not the full social graph — keep consent and revocation records, log access, and minimize fields. NDAs are in place where a client needs them. None of this is a hoop for you to clear before we begin; it is how we operate while we build.

What we plan for on this build

Two things about Spooray shape the engineering, and we account for both:

• A spray is not a single net amount. Its cost splits into a standard bank fee and a small feature fee, and a gift can be pre-scheduled. We model the fee split explicitly and treat a scheduled spray as one record that moves through pending to settled, so it never double-counts when it fires and your reconciliation matches the wallet to the cent.
• The money is naira under a consent regime, but users aren't all in Nigeria. We design the consent flow around the registry and the consent-refresh window so a sync does not silently expire, and for diaspora accounts that sit outside that perimeter we fall back to authorized traffic mapping and reconcile against the same ledger. Access — a consenting account or a sandbox — is arranged with you during onboarding.
• The web app at app.spooray.com can change. When its front end shifts, we re-validate the captured flows as part of upkeep, so the integration keeps matching the live screens instead of drifting.

Where teams actually use this

• A diaspora app that wants to show a user their gifts sent and received — pull the spray ledger and join each transfer to its event for a clean timeline.
• An event or planning tool reconciling what a celebration brought in — total all sprays sharing an event id, split the fees, and hand the host a settled figure.
• A loyalty or reminder layer reading scheduled gifts and the recipient list to nudge a giver before the next birthday fires.

Working with us on Spooray

A working Spooray integration usually lands in one to two weeks. Take it as source-code delivery — runnable API or protocol code plus the OpenAPI spec, tests and interface docs — from $300, and you pay only after it's delivered and you're satisfied. Or skip the build cost and call our hosted endpoints, paying per call with nothing upfront. You give us the app name and what you want out of its data; we handle the access, the consent setup and the rest. Tell us what you're building on the contact page and we'll scope it.

Screens we worked from

The public screenshots below show the spray flow, the wallet and the event surfaces referenced above. Select any image to enlarge it.

How this was put together

Checked in June 2026 against Spooray's own store listing and site, the CBN's open-banking material, and reporting on Nigeria's digital money-spraying scene. The app's features and fee description come from its App Store and Google Play listings and spooray.com; the regulatory points come from the Central Bank of Nigeria and contemporaneous coverage. Primary sources opened:

• Spooray on the App Store
• CBN — Operational Guidelines for Open Banking in Nigeria (PDF)
• TechCabal — Nigeria becomes first African country with open-banking regulation
• Technext — digital money spraying after the CBN ban

Mapped by the OpenBanking Studio integration desk — reviewed June 2026.

Apps in the same money-and-events space

Where Spooray fits, and what a unified integration would sit alongside. Ecosystem context only, in no order:

• Spraay — the closest cousin: guests spray digital naira notes at a celebration, so it holds spray transactions and event records much like Spooray's.
• Nawo — a newer digital money-spraying service built on the same ritual, keeping wallet balances and gift-transfer history.
• OPay — a broad consumer wallet for transfers, bills and savings, with a dense transaction history behind each account.
• PalmPay — a payments wallet for transfers and bill pay; balances and transfer logs sit behind every profile.
• Kuda — a digital bank offering accounts, transfers and savings, with statement data held server-side.
• Moniepoint — payments and business accounts, holding transaction and settlement records for individuals and merchants.
• Paga — a mobile-money service for transfers and payments, with wallet balances and history per account.
• FairMoney — a lending-led digital bank carrying balances, repayment schedules and transaction history.
• Carbon — a credit-led digital bank with a wallet, transfers and loan records held per user.

Integrator questions

Does a spray come back as one amount, or can we see the fee split?

A spray carries its own fee structure rather than a single net figure. Spooray describes its charges as standard bank fees plus a small fee for the entertainment features, so we model the fee split explicitly on each transaction and reconcile it against the wallet movement, which keeps your books matching what actually left and arrived.

Can we tie each gift back to the event it was sprayed at?

Yes. Spraying on Spooray is event-anchored, and the app also handles pre-scheduled gifts, so each transfer references the event it belongs to and a scheduled-fire time where set. We expose that event link in the normalized records so a host or planner can total all the gifts sprayed at one celebration.

What is the legal basis for reaching a Nigerian user's Spooray data?

The account holder's own consent. Nigeria has the CBN Operational Guidelines for Open Banking, released in March 2023 per the CBN circular, which set consent-permissioned data sharing through a registered registry, and the Nigeria Data Protection Act 2023 governs the personal data itself. We work from a consenting account, keep consent and revocation records, and minimize the fields we pull.

Will a pre-scheduled spray show up before it settles?

It can, and we design for it. Scheduled gifts exist as pending records ahead of their fire time, so the sync reads a status field and treats pending, settled and failed states separately. A scheduled spray updates the same record when it fires rather than producing a duplicate, so an upcoming-gifts feed and a settled ledger stay consistent.