KPay (sn.kpay) API integration & OpenFinance services

1. Authorization & session API

Mirrors the KPay app login flow: phone number challenge, OTP verification, device binding, and signed session tokens. Used to bind an end-user once and then call balance, statement, and payment endpoints from your backend without re-prompting for credentials. Includes rotation, revocation and audit logging.

2. Balance & statement query

Reads the KPay wallet balance plus a structured transaction ledger. Each transaction carries type (deposit, retrait, transfert, paiement marchand, achat de crédit, recharge carte bancaire, transfert international), counterparty, amount in XOF, status and reference. Used for accounting reconciliation, anti-fraud and ERP sync.

3. Wallet-to-wallet & international transfer

Programmatic submission of wallet-to-wallet transfers within KPay and outbound international transfers across the CEDEAO corridor. Returns idempotency keys and webhook callbacks so you can settle counter-ledgers without polling. Handles XOF and multi-currency reporting.

4. Bill payment & airtime top-up

Single endpoint that accepts a biller code (SENELEC, WOYOFAL, RAPIDO toll, AQUATECH water) plus account reference and amount. Returns the receipt and a webhook with success / failure. Enables embedding KPay bill-pay inside SaaS portals or property-management dashboards.

5. Merchant payment & cashback engine

QR-code generation, dynamic merchant payment requests, and reconciliation reports for partner outlets. Captures cashback / promotional bonuses (e.g. up to 10% at Low Price supermarkets, EDK stations and Djolof Chicken) so loyalty engines stay accurate.

6. Card-funded wallet recharge

Supports KPay's "recharge by Visa / Mastercard" flow, including 3-D Secure step-up where required, with a clean tokenization layer so card PANs never reach your servers. Useful for diaspora top-ups from EU/US into a Senegalese KPay wallet.

A. SME accounting sync for KPay merchants

A retailer using KPay merchant counters needs daily reconciliation in Sage, Odoo or QuickBooks. We poll the statement API on a 15-minute cadence, normalize each line into a journal entry (debit cash / credit revenue, with VAT split), and push to the ERP via REST. Maps directly to OpenFinance "account information" patterns.

B. Diaspora remittance dashboard

A remittance startup operating EU → Senegal builds a unified dashboard for senders. KPay international transfer status, FX rate and fee fields are fetched via authorized APIs, joined with Stripe / SEPA legs, and surfaced as a single timeline. Webhooks notify the sender when funds land in the recipient's KPay wallet.

C. Property management bill-pay

A property manager with hundreds of Dakar tenants needs to pay Senelec and Woyofal bills monthly. We orchestrate the KPay bill-payment API in batch, retry on transient failures, and produce a CSV ledger plus PDF receipts. Maps to OpenBanking "payment initiation" patterns over a domestic mobile-money rail.

D. Anti-fraud signal for fintech lenders

A lender uses a 12-month KPay statement export as an income / expense proxy. We deliver normalized JSON that scores recurrence (salary deposit cadence, utility-bill regularity, P2P churn) and feeds the lender's underwriting model. Consent and retention windows align with BCEAO Instruction №001-01-2024.

E. Loyalty & cashback program

A merchant network (e.g. EDK fuel stations + Low Price + Djolof Chicken) wants a cross-brand wallet view. KPay merchant-payment events stream through a webhook, the cashback engine applies tier rules, and the customer sees a unified balance. Real KPay promotions (up to 10% at partner outlets) anchor the data model.

Authorize a KPay session (pseudo-code)

POST /api/v1/kpay/auth/session
Content-Type: application/json
X-Studio-Key: <PARTNER_KEY>

{
  "msisdn": "+2217xxxxxxxx",
  "device_id": "studio-bridge-01",
  "consent_id": "ct_2026_04_kpay_001",
  "scopes": ["balance.read","statement.read","payment.write"]
}

200 OK
{
  "session_id": "sess_8f...",
  "access_token": "eyJhbGciOi...",
  "expires_in": 1800,
  "refresh_token": "rt_..."
}

Fetch a transaction statement

POST /api/v1/kpay/statement
Authorization: Bearer <ACCESS_TOKEN>

{
  "wallet_id": "user@kpay.sn",
  "from_date": "2026-03-01",
  "to_date":   "2026-03-31",
  "types": ["TRANSFER","BILL","MERCHANT","INTL"],
  "page": 1,
  "page_size": 100
}

Response (truncated):
{
  "currency": "XOF",
  "items": [
    {"id":"tx_01","type":"TRANSFER","amount":-15000,
     "counterparty":"+2217...","ref":"KP-2026-...","ts":"2026-03-02T08:14:01Z"},
    {"id":"tx_02","type":"BILL","biller":"SENELEC",
     "contract":"3214xxx","amount":-22500,"status":"OK"}
  ],
  "next_page": 2
}

Webhook: merchant payment confirmation

POST https://your-host/webhooks/kpay
X-KPay-Signature: t=1714400000,v1=...

{
  "event": "merchant.payment.succeeded",
  "merchant_id": "MERCH_LOWPRICE_DKR_03",
  "terminal": "POS-22",
  "amount": 12500,
  "currency": "XOF",
  "cashback": { "rate": 0.05, "amount": 625 },
  "tx_id": "kp_tx_77af...",
  "ts": "2026-04-29T11:02:33Z"
}

// Validate HMAC, ack with 2xx within 5s, otherwise retried with exponential back-off.

Deliverables checklist

• Authorization & protocol-analysis report (session, OTP, signing chain)
• OpenAPI / Swagger spec covering balance, statement, transfer, bill-pay and merchant endpoints
• Runnable source code in Python or Node.js (and Go on request)
• Webhook handler templates with HMAC verification
• Test harness with replayable fixtures and sandbox examples
• Compliance notes mapped to BCEAO Instruction №001-01-2024 and Senegal data-protection law

Two engagement models

• Source-code delivery from $300 — runnable API source plus full docs; you pay after delivery once you confirm the build runs end-to-end.
• Pay-per-call hosted API — call our managed KPay endpoint and pay only per request, with no upfront cost; ideal for teams that want usage-based pricing or proof-of-concept work.

About our studio

We are an independent technical studio focused on App protocol analysis and authorized API integration for fintech, e-commerce, mobility and OTT apps. The team blends mobile reverse engineering, payment-rail engineering, and cloud delivery, and we have shipped integrations for WAEMU mobile-money rails, OpenBanking schemes in Europe, UPI in India, and real-time-payment systems in Latin America.

• Marketed to overseas clients, fluent in Senegalese and pan-African mobile-money standards
• Compliant, lawful interface implementations under customer authorization
• Android & iOS coverage, plus Python / Node.js / Go SDKs and OpenAPI documentation
• Pipeline: scoping → protocol analysis → build → validation → compliance hand-off

Contact

For quotes, scope discussions, or to submit your KPay use case, open our contact page:

Open contact page

Engagement workflow

1. Scope confirmation: which KPay surfaces (login, statement, transfer, bill-pay, merchant, international) you actually need.
2. Protocol analysis & API design (2–5 business days, depending on the surface count).
3. Build & internal validation against fixtures (3–8 business days).
4. Documentation, sample requests and test cases (1–2 business days).
5. Typical first delivery: 5–15 business days; KPay developer-portal approvals or sandbox provisioning may extend the timeline.

FAQ

What do you need from me to start?

Is this lawful?

How is data kept private?