Build, operate and maintain the Zakhaa Wallet API.

Looking for an endpoint? Jump to the Endpoint index (every endpoint, sorted by path), the request and response examples (every endpoint with an example payload and response), the services and components catalogue, or search this file for the path, for example cashsend/initiate.

1. Getting started: a 10-minute overview

1.1 Platform overview

Zakhaa Pay is a South African mobile wallet. Every customer gets a Zakhaa wallet holding rand, identified by a 10-digit Zakhaa ID (shown in the app and encoded in their QR code). With it they can:

Businesses get a separate business wallet and can accept online payments through the Zakhaa Pay Checkout gateway: merchants get API keys, create checkout sessions, receive signed webhooks and can refund (13.1–13.5).

Ops, support and compliance staff use the admin dashboard: user management, KYC review, bank reconciliation, campaigns, the gateway admin, refunds and cash devices.

1.2 Who calls this API, and how they prove who they are

One ASP.NET Core process serves five kinds of caller:

1.3 The seven rules that keep everything consistent

1. The ledger is the truth. Every balance change writes a WalletLedgers row (opening, change, closing). Wallet.balance is only a cache of the latest closing balance (§7).
2. Money in is a Topups row, money out is a Withdrawal row, whatever the rail. The app's history is built from both, plus the rail tables (§7.1).
3. Money code locks the wallet (SELECT … FOR UPDATE) and writes the business row and the ledger row in one transaction.
4. "Strict" means two proofs. App money endpoints need a user JWT and a device signature from the same user.
5. Every app endpoint checks ownership. A wallet, user or record ID in a request must belong to the caller, otherwise 403 (§6.3).
6. Two coding styles. Older features are MVC controllers with repositories; newer ones (gateway, refunds, cash devices) are vertical slices in Features/ (§4).
7. Migrations are applied by hand. Nothing migrates on startup (§3.5).

1.4 Recommended codebase reading order

1. Program.cs, then Extensions/ServiceExtensions/* (what is registered) and Extensions/PipelineExtensions.cs (request order).
2. Signing/ (how requests are authenticated) and Signing/CallerExtensions.cs (ownership).
3. Repositories/WithdrawalRepository.cs (Send Zakhaa: the clearest example of a full money transaction).
4. Services/Ledger/DbWalletLedger.cs (reserve → finalise → refund, used by most external rails).
5. Features/Gateway/ (the newest code and the style to copy).

2. Glossary

3. Environments, configuration and deployment

3.1 Environments

Health check: GET /healthz → { description, status, version, env }.

3.2 Secrets

Every secret is a property of Models/SecretKeys.cs, read through AWSSecrets.SecretKeys:

• Production: the whole object is loaded from AWS Secrets Manager when the app starts.
• UAT / local: it's bound from the Config section of appsettings.Development.json.

To add a secret: add a property to SecretKeys, then add the value to Secrets Manager (production) and to Config (UAT).

A missing secret may not be detected during application startup; in many cases, the failure occurs when the relevant integration or service first accesses it. EncryptionKey and JWT_SecretKey throw as soon as anything needs them.

Currently tracked in source control: appsettings.Production.json holds the Nedbank sandbox client ID, secret and certificate password, and Certificates/Sandbox.pfx is tracked. The Nedbank integration is commented out, so nothing uses them, but they should be removed (§16.1).

3.3 Non-secret configuration

The full list of settings is in §18. The ones you'll touch most:

3.4 Deployment

Every deploy deletes and re-extracts the app folder on the server, so nothing stored there survives a deploy.

3.5 Database migrations

Migrations are not applied on startup (the MigrateAsync calls in PipelineExtensions are commented out). To change the schema:

dotnet ef migrations add <Name> --context AppDBContext          # creates Migrations/<timestamp>_<Name>.cs
dotnet ef migrations script <PreviousMigration> <Name> --context AppDBContext -o migrate.sql
# review migrate.sql, run it on UAT, test, then run it on production, then deploy the code

Use ApplicationIdentityDbContext or ApiDbContext for the Identity and OAuth databases. All migrations up to RefundWebhookToken have been applied to production.

Rollback warning: app PINs are upgraded to PBKDF2 when a user logs in (§6.3). Deploying code older than Nov 2026 would lock those users out, so roll forward, not back.

4. Codebase structure and architectural patterns

Program.cs                 composition root (services, then ConfigurePipelineAsync)
Extensions/                DI and pipeline wiring, one file per concern
  ServiceExtensions/       Authentication, Background, Cors, Database, FeatureSlice, Gateway,
                           HttpClient, Identity, Misc (Swagger, rate limiter), Repository
  PipelineExtensions.cs    middleware order, health check, KYC webhook buffering
Controllers/               MVC controllers (style 1)
Repositories/ Interfaces/  data access + business logic for controllers
Services/                  domain services and integration clients
  Gateway/                 checkout payments, refunds, webhook outbox, crypto, rules
  Ledger/                  DbWalletLedger: reserve → finalise / refund
  Processors/              marketing campaign channels (push, SMS, email, in-app, ...)
Features/                  vertical slices (style 2): Gateway, Refunds, CashDevices
Common/                    Result<T>, Error, messaging (ISender, ICommand, IQuery, behaviours)
Signing/                   auth handlers and attributes, outbound request signing
Background/                hosted services and the background task queue
Data/                      DbContexts (AppDBContext split into partial files per domain)
Models/ DTOs/ Mappers/ Enums/ Utilities/
Migrations/                EF Core migrations (AppDBContext; ApiDb/ and ApplicationIdentityDb/ for the others)
tests/WalletApi.Gateway.Tests   xUnit tests
docs/                      (gitignored)

4.1 MVC controllers and repository pattern

A controller action validates input, often checks an OTP, calls a repository, and returns Ok(new ServerResponse(success, message, data)). Business logic lives in Repositories/*Repository.cs (for example WithdrawalRepository.CreateAsync for Send Zakhaa). JSON is Newtonsoft (enums as strings).

Note that many older endpoints return HTTP 200 even on failure, with success: false in the body. Check the body, not only the status.

4.2 Vertical slice architecture

Each feature folder holds its request, handler and endpoint together:

public static class GetFeePlan
{
    public sealed record Query(string Id) : IQuery<Result<object>>;
    public sealed class Handler(AppDBContext db) : IRequestHandler<Query, Result<object>> { ... }
}
public sealed class GetFeePlanEndpoint : IEndpoint
{
    public void Map(IEndpointRouteBuilder app) =>
        app.MapGet(AdminApi.Prefix + "/fee-plans/{id}", async (string id, ISender s, CancellationToken ct) =>
            (await s.Send(new GetFeePlan.Query(id), ct)).ToHttpResult())
           .RequireGatewayAdmin();
}

• IEndpoint classes are discovered by reflection and mapped by app.MapEndpoints().
• ISender is an in-house dispatcher (no MediatR). Behaviours in Common/Messaging/Behaviors.cs:
  • run FluentValidation (failures become 422 validation_error);
  • wrap every ICommand in a DB transaction. A command that locks rows, commits in steps or calls outside services implements IManagesOwnTransaction to opt out.
• Result<T>.ToHttpResult() maps error types to HTTP: Validation and Unprocessable → 422, NotFound → 404, Conflict → 409, Forbidden → 403, Unauthorized → 401, BadRequest → 400.

4.3 Adding an endpoint (checklist)

1. Create Features/<Area>/<Action>/<Action>.cs with the request, handler and an IEndpoint.
2. Pick the right auth (§6): RequireMerchantApiKey(), RequireGatewayAdmin(), .RequireAuthorization("ApiClient:…"), or [AuthorizeStrict] for app endpoints.
3. If it moves money: lock the wallet row, write Topups or Withdrawal and a ledger row in one transaction, and use IManagesOwnTransaction if you manage commits yourself.
4. Audit admin writes (AdminAuditService.AuditAsync).
5. Add tests in tests/WalletApi.Gateway.Tests.
6. Add it to this handbook (§12 and §15).

5. Request pipeline

Order of middleware (Extensions/PipelineExtensions.cs):

1. UseForwardedHeaders: the real client IP comes from X-Forwarded-For.
2. UseRateLimiter (§6.11).
3. UseHttpsRedirection.
4. Development only: Swagger and seed data.
5. MapHealthChecks("/healthz").
6. UseRouting, UseCors() (default policy; named policies per endpoint).
7. UseAuthentication, UseAuthorization.
8. MapHub<NotificationHub>("/notifHub") (CORS SignalRCors).
9. UseKycWebhookBuffering: lets the Didit webhook read its raw body for HMAC checking.
10. MapControllers(), then MapEndpoints() (slices).

Path base. Production serves everything under /v2, but inside the app Request.Path excludes it. This matters for device signatures (§6.2).

6. Security

6.1 Overview: who can call what

Bearer and WebJwt tokens (app, admin and web) are signed with the same key, issuer and audience (JWT_* secrets). A plain [Authorize] therefore accepts any of them. What separates an admin from an app user is the role check ([Authorize(Roles=…)]), the device signature (Strict), and the ownership checks inside each action (§6.3). Using separate keys per token type is an open item (§16.1).

Roles (Identity/RoleNames): SuperAdmin, Admin, SupportAdmin, MarketingAdmin, Sales. In this handbook, "admin+support" means SuperAdmin, Admin or SupportAdmin.

6.2 Mobile app requests: JWT + device signature ([AuthorizeStrict])

Every money-moving and personal-data app endpoint uses [AuthorizeStrict] (policy JwtAndDevice). The policy needs three things.

(a) A user JWT (Authorization: Bearer …), from Utilities/JwtToken.GenerateAccessToken:

• signed with HMAC-SHA256;
• claims NameIdentifier = Name = the user's ID, and Role = "1";
• valid 30 minutes; issuer and audience from secrets.

(b) A device signature, checked by DeviceAuthenticationHandler. Required headers:

Canonical string (lines joined with \n):

METHOD
PATH            ← Request.Path WITHOUT the /v2 path base, e.g. /api/withdrawal
TIMESTAMP       ← the X-Timestamp value
REQUEST_ID      ← the X-Request-Id value
BODY_HASH       ← base64(SHA-256(raw body)); an empty body hashes ""

The handler rejects a request when:

• a header is missing or the timestamp isn't a number;
• the X-Request-Id was already seen in the last 10 minutes (replay protection, in-memory cache);
• the timestamp is more than 3 minutes from server time;
• the device is unknown or not active;
• the signature doesn't verify against the device's stored public key (SPKI BEGIN PUBLIC KEY, or PKCS#1 BEGIN RSA PUBLIC KEY).

On success it adds the claims device_id and device_user_id.

(c) Same user. MultiSchemeHandler requires the JWT's NameIdentifier to equal the device's device_user_id. If either identity is missing, it fails closed. A stolen token is useless without the phone, and a phone can't act for another user.

Example:

POST /v2/api/withdrawal
Authorization: Bearer eyJhbGciOi...
X-Device-Id: 7b1f...
X-Timestamp: 1762611200000
X-Request-Id: 2c0b8e7a-...
X-Signature: base64(sign("POST\n/api/withdrawal\n1762611200000\n2c0b8e7a-...\n<sha256 body>"))

6.3 Ownership: the caller may only touch their own data

Strict proves who is calling. Each action then checks that every ID in the request belongs to the caller, using Signing/CallerExtensions.cs:

A failed check returns 403. Where a request body carries a UserId, the caller's own ID replaces it (CashSend, vouchers), or the request is rejected if they differ (add-business, Send Zakhaa and PayShap OTPs).

For all new endpoints: use [AuthorizeStrict], then call one of these helpers before reading or changing anything.

6.4 App login, device binding, OTPs and PINs

New phone:                                              Returning user (bound phone):
1. POST /api/auth/login {phone_number, password,        1. POST /api/auth/device/challenge   (Device-signed)
   deviceId}                                               {AuthType: "PIN"|"Biometrics", PIN?, DeviceId}
   → checks the PIN, emails an OTP keyed by deviceId       → for PIN: checks it; returns a random 32-byte
     (no token yet)                                          challenge (cached 5 minutes)
2. POST /api/auth/device/bind {UserId, DeviceId,        2. POST /api/auth/device/verify       (Device-signed)
   PublicKey, OTP, device info}                            {DeviceId, SignedChallenge, LocalVersion}
   → verifies the OTP, registers the device                → verifies the RSA signature of the challenge
     (deactivates the user's previous device and pushes     → access token + refresh token + full user data
     "Device unlinked" to it)
   → access token + refresh token + full user data

Registration (/api/auth/register, /register/business):

1. The PIN is validated first (6–8 characters including a digit), so a bad PIN doesn't use up the OTP.
2. The OTP is verified (requested with /api/auth/otp, type EmailVerification).
3. In one transaction: the user, a personal wallet, settings and notification preferences are created. A business also gets a Business row and a business wallet. An optional promo code credits the wallet, with a ledger row.
4. The device is bound and tokens are returned.

Login messages: an unknown phone number and a wrong PIN both return "Incorrect phone number or PIN…". Login emails the device-verification OTP directly through OtpSmsService.

OTPs (Utilities/OtpSmsService):

Where OTPs are required:

• registration and device binding;
• Send Zakhaa from R500, which must be the logged-in user's OTP;
• every PayShap payment, again the logged-in user's;
• password, phone and email changes, and forgot-password.
• CashSend needs no OTP (by decision).

PIN storage:

• PBKDF2-HMAC-SHA256, 210,000 iterations, 32-byte random salt, stored as pbkdf2$<base64> in Users.password (salt in Users.salt), via PasswordValidator.HashPin and VerifyPin.
• Older SHA-256 hashes still verify and are replaced with PBKDF2 at the next successful login.

App tokens:

• The access token lasts 30 minutes.
• JwtToken.GenerateRefreshToken creates a 14-day JWT with audience {JWT_ValidAudience}-refresh, so it can't be used as an access token. It's set as the HttpOnly, Secure cookie refresh_token (domain .zakhaapay.com) and returned at registration.
• The app has no refresh endpoint: it re-authenticates with the device challenge (step 1–2 above, right).

Login attempts (success or failure, method, reason) are recorded in AuthenticationInfo.

6.5 Admin dashboard (/api/admin-auth)

ASP.NET Identity (ApplicationIdentityDbContext) plus AdminAuthSecurityService:

• Passwords: Identity's PBKDF2 hasher.
• Lockout: 5 failed attempts lock the account for 15 minutes (HTTP 423). An email alert goes to LockoutAlertTo, and the attempt is logged with a hashed email and the source IP.
• Two-factor login is mandatory:
  • an admin without it gets 428 TwoFactorSetupRequired and must enrol: 2fa/setup → 2fa/enable, with a 10-minute single-use setup token (purpose=2fa-enable);
  • TOTP keys are stored encrypted (§6.8) and recovery codes hashed;
  • using a recovery code forces 2FA to be reset and re-enrolled.
• Tokens:
  • access token from TokenProvider (claims sub, email, roles), valid ExpirationInMinutes (default 5);
  • refresh token: 32 random bytes, only its SHA-256 stored (RefreshTokens in the Identity DB), sent as the HttpOnly cookie refreshToken, rotated on every refresh (the old one is revoked and linked to its replacement), valid RefreshTokenExpirationDays (default 7).
• Admin user management: register and unlock-account need Admin or SuperAdmin; role, status and delete need SuperAdmin.
• Audit: every admin write is logged to AuditLogs (AdminAuditService), readable at GET /api/audit.

6.6 Partners: OAuth client credentials (ApiClient)

• Token request: POST /api/client-auth/token, form fields grant_type=client_credentials&client_id=…&client_secret=… (rate-limited).
• Client secrets are stored as BCrypt hashes in OAuthClients (ApiDbContext). The client must be Active.
• The JWT:
  • claims sub (client ID), jti, iat, client_name, and scope (taken from the client record; a requested scope is ignored);
  • issuer, audience and key are the JWT secrets with -api-client appended;
  • lifetime is per client (TokenLifetimeSeconds).
• Issuing a token revokes the client's other active tokens, except for Pay@, which may hold several. Every token is recorded in OAuthTokens by jti.
• [ValidateApiClientToken] (on Pay@ and the EFT Corp QR lookup) and its endpoint-filter twin (on cash devices) also check the jti is known, not revoked and not expired. Revocation takes effect immediately.
• Managing clients: /api/admin/api-clients (SuperAdmin only) registers {ClientId, ClientSecret, Name, Scope, TokenLifetimeSeconds}, and can suspend, activate, rotate the secret or revoke all tokens.

6.7 Merchants: API keys (gateway)

MerchantApiKeyAuthenticationHandler:

• The header is Authorization: Bearer sk_test_… or sk_live_…, 40–128 characters.
• The key is looked up by its first 12 characters (Prefix) among unrevoked keys. Its SHA-256 is compared in constant time; the raw key is never stored and is shown once at creation.
• The key's mode must match its prefix. A suspended merchant is rejected, and a sk_live_ key also requires the merchant to be live.
• Claims: merchant_id, merchant_mode, merchant_key_id. last_used_at is updated at most once a minute.
• Webhook signing secrets are stored encrypted (MerchantSecretStore). On rotation the old secret stays valid for 24 hours, so webhooks carry two v1= signatures during that window.
• Outgoing webhooks: X-Zakhaa-Signature: t=<unix>,v1=hex(HMAC-SHA256(secret, t + "." + body)) and X-Zakhaa-Event-Id.
• Checkout links carry a signed key. The public /verify and /return endpoints answer every failure with the same 404 checkout.unverifiable, so nobody can probe which refs exist.

6.8 Encryption and outbound signing

• EncryptionService:
  • AES-256-GCM (authenticated, so tampering is detected), stored as gcm: + base64(nonce, tag, ciphertext), key EncryptionKey;
  • values written before Nov 2026 are AES-CBC without a prefix and still decrypt;
  • used for admin TOTP keys, merchant signing secrets and Zakhaa voucher PINs.
• Voucher PINs are encrypted by an EF Core value converter (VoucherPinCrypto in Data/AppDBContext.ZakhaaVoucher.cs), so code and the app see the plain PIN while the database holds ciphertext.
• ApiSigningHandler signs calls to Zakhaa's own middlewares (PayShap, CashSend, …). It adds X-Date, X-Client-API-Key (MIGKeyId), X-Nonce and X-Signature: RSA-SHA256 with RSA_Private_Key over X-Date:{date}\r\nX-Client-API-Key:{id}\r\n{body}.

6.9 Real-time (SignalR /notifHub)

CORS policy SignalRCors allows https://pay.zakhaapay.com (and localhost).

6.10 Inbound callbacks: how each is verified

6.11 Rate limits and CORS

Rate limits (all return 429, Retry-After: 60, code rate_limited):

The client IP comes from X-Forwarded-For, trusted only from a proxy on the same machine (loopback), which is how production runs.

CORS (CorsExtensions):

6.12 Files and KYC documents

Uploads (FileUploadService):

• at most 5 MB;
• the MIME type and extension must match an allow-list;
• each file is virus-scanned by ClamAV (ClamAV_Host/ClamAV_Port), and infected files are rejected;
• stored in S3 (BucketName).

Users may only reach their own documents; staff can reach anyone's to review KYC. Campaign media is also stored in S3.

7. Money: wallets, ledger, fees, limits, holds, fraud

7.1 Tables

7.2 Rules for writing money code

1. Lock the wallet row (SELECT … FOR UPDATE). Send Zakhaa locks both wallets in ID order to avoid deadlocks, inside a serializable transaction.
2. Read the opening balance from the last ledger row, never from Wallet.balance.
3. Write the Topups or Withdrawal row and the ledger row in the same transaction. Set Wallet.balance = ClosingBalance.
4. ChangeAmount is positive; Direction gives the sign.
5. Do notifications only after the commit.

7.3 Fees

• FeeRepository.ApplyFee(wallet, withdrawal, code): fee = amount × pct% or the fixed amount, and VAT = 15% of the fee. The payer pays amount + fee + VAT.
• Codes in use:
  • ZAKPEER: Send Zakhaa of type Payment;
  • ZAKVOUCHER: other Send Zakhaa types;
  • CASHDEVICE_DEPOSIT, CASHDEVICE_WITHDRAWAL: cash devices;
  • VAS, PayShap and other rails use their own codes;
  • gateway merchants use fee plans made of fee codes (docs/admin-dashboard-gateway.md).
• The payer of a gateway order pays no fee; the merchant pays the gateway fee.

7.4 Limits and trust tiers

Every debit goes through these checks in order (the same order in DbWalletLedger and Send Zakhaa):

1. Frozen (trust_tier_frozen) → blocked: "temporarily restricted".
2. Unverified ceiling: an unverified user can't exceed the Unverified limit per day.
3. Trust-tier daily cap (Utilities/TrustTierPolicy):

Outgoing payments are ledger debits, excluding refund types. A manual trust_tier_override on the wallet is honoured. TrustTierRecomputeJob recomputes tiers on a fixed schedule (first slot 02:00 SAST), skipping frozen wallets and overrides.

4. Platform daily limit (TransactionLimit Daily) and monthly limit (Monthly). Send Zakhaa also checks the Withdrawal limit for non-payment types.
5. Spendable balance (after holds, §7.5). If the amount fits but the fees don't, the error states the maximum you can send.

LimitRefresherBackgroundService resets dailySpent daily, and monthlySpent on the 1st of the month (SAST).

7.5 Deposit holds

PayshapPolicy.ComputeSpendableAsync (Utilities/PayshapEligibility.cs):

• Recent card and EFT deposits (references matching ^ZP-[A-Z0-9]+-[0-9A-F]{8}(:\d+)?$) are held:

• Other recent credits (not Send Zakhaa) are also checked within a 30-minute window.
• Spendable = balance − held. The balance endpoint and login data show spendable amounts.
• The refund service lets a merchant also use the held credit of the payment it's refunding.
• PayShap has extra limits: 2 per day, at least 30 minutes apart (PayshapPolicy.ComputeAsync → can-pay).

7.6 Fraud model

DbWalletLedger.ReserveAsync (used by VAS, PayShap, Zapper, Scan to Pay app payments and CashSend) calls the fraud model before reserving funds:

• FraudFeatureBuilder builds the features, and FraudPredictionService posts them to /fraud/predict.
• A score of 0.70 or more writes an AML_Flags row (risk high from 0.75, otherwise medium) and blocks the payment: "Unable to process this transaction at the moment".
• If the fraud service is down, the call throws and the payment fails (fails closed).
• Send Zakhaa (WithdrawalRepository) does not call the fraud model.

7.7 Reserve → finalise → refund (DbWalletLedger)

For rails that call an outside provider:

1. Reserve: run the checks above, debit the wallet with a ledger row, and create a pending rail record.
2. Call the provider.
3. Finalise on success: mark the record completed, and the debit stays.
4. Refund on failure: credit the money back with a *_refund ledger row.

Polling jobs (§10) finish payments whose outcome arrives later.

8. Databases

PostgreSQL through Npgsql, with three DbContexts (DatabaseExtensions.cs, connection from the DB_* secrets):

AppDBContext partial files:

The gateway tables use snake_case names. checkout_sessions uses Postgres xmin as a concurrency token; lock it with SELECT *, xmin FROM checkout_sessions … FOR UPDATE.

9. External integrations and inbound callbacks

10. Background jobs

The test host disables hosted background services through ApiFactory.

11. Response conventions

• Older controllers: ServerResponse { success, message, data }, often with HTTP 200 even on failure. Some newer controller actions use Result<T>. Amounts are decimal rand.
• Slices (gateway, refunds, cash devices): { "isSuccess": bool, "data": …, "error": { "code", "description" } } with correct HTTP status codes and stable snake_case error codes. Gateway and refund amounts are integer cents.
• Flash VAS request amounts are cents too ("amountInCents": 2900 = R29.00).
• New admin list endpoints are paged: page, pageSize → items, totalRecords, totalPages, currentPage, pageSize, hasNextPage, hasPreviousPage.

12. Endpoint reference

Paths are shown without the path base: prefix them with /v2 in production. Strict = [AuthorizeStrict] (user JWT + device signature from the same user, §6.2). admin+support = SuperAdmin, Admin or SupportAdmin. Example request and response bodies for every endpoint are in §20.

12.1 Auth and devices: api/auth

Request/response examples: §20.1

Example:

curl -X POST {host}/v2/api/auth/login -H 'Content-Type: application/json' \
  -d '{ "phone_number": "0821234567", "password": "••••••", "deviceId": "7b1f..." }'

Terminals: POST api/auth/terminal/session (anonymous, SessionDto) looks the user up by ID number and registers a business for them if none exists.

12.2 Admin auth and admins: api/admin-auth, api/admin

Request/response examples: §20.2

12.3 Users, KYC, documents, notes

Request/response examples: §20.3

12.4 Wallets, balances, transactions

Request/response examples: §20.4

12.5 Send Zakhaa (wallet to wallet) and withdrawals: api/withdrawal

Request/response examples: §20.5

All endpoints are Strict.

Example:

POST /v2/api/withdrawal
{
  "wallet_id": "ZP1234567890", "receiver_id": "ZP0987654321",
  "amount": 150.00, "method": "Send Zakhaa", "reference": "Rent share",
  "otp": "123456", "type": "...", "uid": "<user guid>"
}

Both users get a push notification.

12.6 PayShap: api/payment

Request/response examples: §20.6

All endpoints are Strict.

12.7 Scan to Pay, QR and NFC: api/stp, api/qr/lookup

Request/response examples: §20.7

12.8 Zapper, CashSend, vouchers, Pay@

Request/response examples: §20.8

Every Pay@ and EFT Corp lookup endpoint also runs [ValidateApiClientToken], which rejects API-client tokens that are unknown, revoked or expired.

12.9 VAS via Flash: api/flash

Request/response examples: §20.9

All endpoints are Strict. Flash amounts are integer cents ("amountInCents": 2900 = R29.00; the [JsonPropertyName("amount")] attribute on that property is ignored by Newtonsoft, §20.0). Purchases go through Execute(req.ToOp()): reserve funds through the ledger, call Flash, then finalise or refund.

Example (airtime):

POST /v2/api/flash/cellular/pinless/purchase
{ "walletId": "9471452626", "merchantAccountNumber": "0821234567", "productCode": "<Flash product code>",
  "mobileNumber": "0821234567", "amountInCents": 2900, "reference": "...", "paymentMethod": "..." }

12.10 Notifications, settings, content

Request/response examples: §20.10

12.11 Admin operations

Request/response examples: §20.2 · §20.11

12.12 Payment gateway: merchant API (api/checkout-sessions, API key)

Request/response examples: §20.12

The public contract is in docs/merchant-integration-guide.md. Summary:

Portal (no auth, portal CORS, public rate limiter):

12.13 Payment gateway: admin (/api/gateway/admin, SuperAdmin or Admin)

Request/response examples: §20.13

Full contract: docs/admin-dashboard-gateway.md.

Every write is audited (GATEWAY_* actions in AuditLogs).

12.14 Refunds (/api/admin/refunds, SuperAdmin or Admin)

Request/response examples: §20.14

12.15 Cash devices

Request/response examples: §20.15 · §20.16

Partner API (/api/cash-devices, ApiClient:PaySolution):

Admin (/api/admin/cash-devices, amounts in cents): GET /devices, /transactions, /transactions/{zakhaaReference}, /collections, /withdrawal-requests, /reversals.

13. Key flows, end to end

13.1 Gateway checkout with a card or bank app (EFT Corp)

Request/response examples: §20.12 · §20.13

Merchant ─POST /api/checkout-sessions──────────▶ API: session CREATED, checkoutUrl signed (HMAC "key")
Buyer ───opens pay.zakhaapay.com/qr?...&key── ▶ GET /checkout-sessions/{ref}/verify  (link check)
Buyer ───picks Apple Pay / bank app ─────────▶ POST /api/stp/initiate/xpay
                                               API: amount = server-held total, reference = "{walletId}:{ref}"
                                               → EFT Corp middleware → buyer approves in their app
EFT Corp ─POST /api/stp/callback (encrypted)─▶ decrypt → StpCallbacks row → 200 → background:
                                               VerifyAsync(txn) → CompletePaymentAsync:
                                               merchant Topups ("{ref}:{txn}", method eftcorpSTP) + ledger,
                                               gateway fee entries, session SUCCESSFUL,
                                               webhook_events row (outbox, same transaction)
WebhookDeliveryWorker ─payment.succeeded (signed)─▶ merchant notifyUrl

• Fees: from the merchant's fee plan (fee codes in Fees). The merchant is credited net; fee and VAT ledger entries are written.
• Reconciliation: EXACT, UNDERPAID or OVERPAID (the tip counts).
• Review flags: LATE (paid after expiry or cancel), DUPLICATE (a second payment), WALLET_MISMATCH, MODE_MISMATCH. Flagged sessions go to the review queue and are not expired by the expiry job.
• If crediting fails permanently, the payment is reversed with EFT Corp. Transient failures stay pending for the sweep.

13.2 Gateway payment through Send Zakhaa

Request/response examples: §20.5

When POST /api/withdrawal carries a reference equal to an open checkout ref (or {walletId}:{ref}) for the receiving merchant wallet:

• Live mode: the payer is debited without the ZAKPEER fee, the merchant is credited ("Merchant payment") with the gateway fee entries, the session becomes SUCCESSFUL (processorPaymentId = "zw_{withdrawalId}"), and payment.succeeded is queued.
• Test mode: no money moves. The session is marked paid and the app gets a normal success response.
• The wrong wallet, a closed or already-paid session, or a suspended merchant is rejected before any money moves.

13.3 EFT Corp callback processing (StpCallbackProcessor.ResolveAsync)

Request/response examples: §20.7

1. Verify with EFT Corp (GET purchase/notification/{txn}), retrying while PENDING.
2. Approved and ours (merchant ID, ZAR, exact reference) → credit (idempotent).
3. FAILED, REVERSED, DECLINED, CANCELLED or REFUNDED:
   • first, PaymentRefundService.ConfirmFromEftAsync: is this one of our refunds or reversals? If so, settle it;
   • otherwise claw back any credit (ScanToPayService.ReverseTransactionAsync).
4. Webhooks without walletId:ref are accepted only for a transaction or ref we already know (ScanToPayController.KnownReferenceAsync).

13.4 Refund through Send Zakhaa (wallet rail)

Request/response examples: §20.12 · §20.14

PaymentRefundService.RefundAsync, rail zakhaa_wallet:

1. Lock the payment's Topups row (FOR UPDATE); remaining = gross − succeeded refunds; one pending refund at a time.
2. Check the receiver can pay (spendable balance + this payment's own held credit).
3. One transaction: receiver Withdrawal "Refund to {payer}" + ledger debit; payer Topups "Refund from {merchant}" + ledger credit.
4. If it's a session's payment: refundedAmountCents goes up, the session becomes PARTIALLY_REFUNDED or REFUNDED, and payment.refunded is queued (a duplicate refund keeps the order paid and sends refund.duplicate: true).
5. Push notification to the payer (TransactionType.PaymentRefunded).

13.5 Refund through the bank (EFT Corp rail)

Request/response examples: §20.7 · §20.14

1. Choose the operation: a reversal (DELETE purchase/{txn}) for the full amount on the same SAST day with nothing refunded before; otherwise a refund (POST purchase/doRefund/{txn} with {amount, webhook}).
2. Commit first: a PENDING refund row + a pending receiver Withdrawal (funds held). For refunds, a fresh random token is created and only its SHA-256 is stored; the webhook URL is {EftCorp:RefundWebhookBaseUrl}/{refundId}/{token}.
3. Call EFT Corp. Rejected → FAILED and the funds are released (codes 445 debit card, 444/514 not reversible, 515, 432, 436, 513 are mapped to plain messages). Timed out → stays PENDING.
4. The outcome arrives by webhook:
   • Refund: POST /api/stp/refund-webhook/{refundId}/{token} (token checked, 200 straight away, background job verifies with EFT Corp: the record must point at the original purchase);
   • Reversal: the merchant notification REVERSED.
5. Only bank response 00 counts as success. A failed reversal is also reported as REVERSED.
6. Fallbacks: POST /api/admin/refunds/{id}/check, then /settle.

13.6 PayShap send

Request/response examples: §20.6

(Full details: 13.14.)

initiate-payment → eligibility (PayshapPolicy) → DbWalletLedger reserves → middleware call (signed) → PayshapStatusBackgroundService polls → finalise (debit stays) or refund (reservation released) → notification.

13.7 Pay@ cash deposit

Request/response examples: §20.8

Account number = 13010 + wallet ID. Limits R10–R15,000. Fee DEPOSIT (fallback DEPOSIT/TRANSFER) + 15% VAT is deducted, and the net is credited with reference PayAt Top-up, ID: …. Completions without a prior authorisation (store-and-forward) are still credited from the tenders. Pay@ reversals aren't implemented. Errors return 500 so Pay@ retries.

Retailer scans the wallet's Pay@ barcode → account/enquiry → transaction/authorization (PayAtPendingTopups) → transaction/completion credits the wallet (Topups + ledger), or transaction/void cancels.

13.8 Send Zakhaa (wallet to wallet)

Request/response examples: §20.5

WithdrawalController.Create → WithdrawalRepository.CreateAsync:

1. Controller checks: a user JWT and device signature (Strict); the sender wallet's user_id must equal the JWT user (else 403); an OTP from R500.
2. Serializable transaction, both wallets locked FOR UPDATE in ID order.
3. Rejections: sending to the same wallet, an amount ≤ 0, or a frozen sender.
4. Gateway check: if the reference is an open checkout session for the receiver, it follows gateway rules instead (13.2).
5. Limits: the Withdrawal limit, CheckLimits (unverified, daily, monthly), then the trust-tier cap.
6. Fee: ZAKPEER or ZAKVOUCHER (0 for gateway orders), plus 15% VAT on the fee. Total = amount + fee + VAT.
7. Balance: the opening balance comes from the last ledger row; the spendable balance is checked (holds), with explicit messages for "held funds" and "fees push you over".
8. Writes: sender Withdrawal (Completed) and a debit ledger row send_zakhaa; the beneficiary is saved; the receiver gets a Topups row and a credit ledger row (or the merchant credit for a gateway order). One SaveChanges and commit.
9. After commit: a SignalR TransactionUpdate to the receiver, push and in-app notifications to both, and a payment-result broadcast for the web or desktop page.

13.9 Buying airtime or another VAS product

Request/response examples: §20.9

FlashController → Execute(req.ToOp()) → VasService:

1. DbWalletLedger.ReserveAsync runs the limit checks (§7.4), the fraud model (§7.6) and the spendable-balance check, debits the wallet and creates a VasTransactions row.
2. Flash is called.
3. On success it's finalised (receipt, voucher PIN or token). On failure RefundAsync credits the money back (vas_refund).

VasService.CheckBalanceAndTopUp monitors the Flash float.

13.10 Cash devices (PaySolution)

Request/response examples: §20.15 · §20.16

• Deposit (POST /api/cash-devices/transactions, type 1): idempotent per device + transaction reference. Fee CASHDEVICE_DEPOSIT; the wallet is credited with a ledger row.
• Withdrawal:
  1. POST /withdrawals/request checks the wallet and balance and sends a one-time code (4–8 digits, valid 5 minutes, only its salted hash stored, 3 attempts) to the holder's app. A new request cancels earlier pending ones; a retry with the same request reference doesn't send a second code.
  2. The device then submits type 3 with the code. The wallet is debited, with fee CASHDEVICE_WITHDRAWAL.
• Reversal (POST /withdrawals/reverse): within 24 hours, for cash not dispensed. It refunds amount + fee + VAT and is claimed atomically, so it can't refund twice.
• Collection (type 2): a cash-in-transit pickup. Records the expected amount (deposits minus dispensed withdrawals since the last collection) and the variance. No money moves.

13.11 How money gets into a wallet (every source)

Request/response examples: §20.4 · §20.11

13.12 Zakhaa vouchers (cash-like vouchers between users)

Request/response examples: §20.8

• Create (POST /api/vouchers/create, {UserId, PIN, WalletId, Amount}):
  • runs in a serializable transaction with the wallet locked;
  • applies the same checks as Send Zakhaa (frozen, Withdrawal limit, daily/monthly/unverified limits, trust-tier cap, spendable balance), and fee ZAKVOUCHER + 15% VAT;
  • creates a 12-digit voucher number (cryptographic RNG, unique) valid 1 year, a Withdrawal row (Zakhaa Voucher) and a debit ledger row zakhaa_voucher_purchase;
  • stores the PIN encrypted (AES-GCM; decrypted transparently when read, so the app still sees it).
• Redeem ({Voucher, WalletId}): locks the voucher, checks it isn't expired, reversed or redeemed, then credits the target wallet (Topups + ledger topup) and marks it redeemed. The PIN isn't required. The target wallet must belong to the logged-in user; an unknown wallet gets "Zakhaa wallet not found."
• Reverse ({UserId, Voucher, WalletId}): only while unredeemed and unexpired; refunds the creator's wallet. Only the creator (the logged-in user) can reverse, into their own wallet.
• Expiry: SetExpiredAsync refunds an expired voucher.
• Lookup by number returns the voucher including its PIN; listing by wallet is limited to the caller's own wallets.

13.13 CashSend (send cash to a phone number)

Request/response examples: §20.8

Through TransMS / ABSA, via Zakhaa's middleware (payshap.zakhaapay.com):

1. Initiate (/api/cashsend/initiate):
   • de-duplicated on user, reference, same day and amount;
   • a per-transaction CallbackToken is generated;
   • DbWalletLedger.ReserveAsync (product CASHSEND: limits, fraud, holds) debits the wallet;
   • TransMS Initiate is called with mobile number, amount, references, beneficiary name, note, callback URL and token. If it's rejected (RJCT) the money is refunded; otherwise the record is finalised.
2. Statuses: Pending → Active (bank accepted, withdrawal number sent to the recipient) → Redeemed (cash collected) | Cancelled (refunded) | Rejected/Failed (refunded).
3. Cancel, resend withdrawal number and reset PIN call TransMS. Cancel is only allowed in Pending/Active once TransMS has given a CashSendId; the final state arrives by webhook.
4. Webhook (/api/cashsend/webhook):
   • matched by end-to-end ID (our reference) or UETR;
   • Cancelled/Rejected refund the wallet (cashsend_refund);
   • recovery case: if our side had marked it Failed (and refunded) but TransMS reports it initiated, the wallet is debited again and a new Active row is added.
   • the X-Callback-Token header must match the transaction's CallbackToken, otherwise 401 and nothing changes.
5. Stored data: mobile number, beneficiary name, note, WithdrawalNumber, UETR, IP address. The collection PIN is no longer stored (older rows may still hold one).
6. Access: no OTP; the wallet must belong to the logged-in user, whose ID replaces any UserId in the body.

13.14 PayShap (pay a bank account)

Request/response examples: §20.6

• Eligibility: GET /api/payment/can-pay/{wallet} (2 per day, 30 minutes apart, available amount).
• Pay (POST /api/payment/initiate-payment):
  1. The OTP is checked and the wallet ownership verified.
  2. Duplicates are rejected (same user, reference, day and amount). A new TransRef GUID is set.
  3. ReserveAsync (PAYSHAP) debits the wallet.
  4. The middleware POST /admin/mig/initiate-payment is called (signed). Unless it fails, the record is finalised, the beneficiary saved (account number, type, branch, holder, bank) and a push sent. On failure it's refunded with the bank's reason.
• Follow-up: PayshapStatusBackgroundService polls GET /admin/mig/status/{ref} every minute. It moves Pending to Completed or Failed (refunding on failure), and also handles a late Failed → Completed.
• Stored data: account details in PayshapBeneficiary; PayshapTransactions holds UniqueEftNumber, PaymentNumber, ApiRef, IP address.

13.15 Zapper and Scan to Pay (paying a merchant's QR from the app)

Request/response examples: §20.7 · §20.8

• Zapper:
  • initiate decodes the scanned base64 QR via the Zapper middleware;
  • finalize de-duplicates (user, reference, day, Pending/Completed), reserves funds (ZAPPER) and notifies Zapper "success" with the amount in cents. On success it's finalised and a push sent; on failure it's refunded and Zapper is told "failed".
• Scan to Pay (app):
  • initiatestp stores a ScanToPay row and fetches the QR's details (amount, merchant name, reference) from the EFT Corp middleware;
  • finalizestp (ownership checked): one payment per QR, same reference by the same user blocked for 3 minutes, reserve (SCAN2PAY), then the middleware Finalize. A PENDING result is polled twice, 5 seconds apart; anything not SUCCESSFUL is refunded. Success → finalised, push sent, and the EFT Corp float check is queued.
  • The tip (AdditionalFields.tipAmount) is added to the wallet debit inside DbWalletLedger.ReserveAsync and recorded as TipAmount; the same total is sent to EFT Corp.
  • ScanToPayStatusBackgroundService (20 s) settles pending ones and refunds failures.
• Floats: when the EFT Corp tenant wallet is ≤ R2,000, PayshapService.LoadEFTCorpWallet (/admin/mig/eftcorp) tops it up (10-minute cooldown). Flash has the same mechanism (/admin/mig/flash, 15-minute cooldown).

13.16 NFC tags (tap to pay a person)

Request/response examples: §20.7

• Generate (Strict; the wallet must be Active): a random opaque TagId and a URL to write onto the tag. Status Pending.
• Life cycle: activate (Pending→Active), deactivate (Active→Inactive), reactivate, revoke, abandon. All require the tag to belong to the given wallet.
• Resolve (GET /api/stp/nfc/tags/resolve/{tagId}, public): returns the wallet to pay only if the tag is Active and the wallet is active. Every other case returns the same tag_unavailable, so tag IDs can't be probed.

13.17 Bank reconciliation (unmatched deposits)

Request/response examples: §20.11

• Statement lines live in StatementTransactions and are loaded outside this API: nothing in this code inserts them.
• Unmatched credit: a statement line with Amount > 0 with no top-up where amount + fee + vat equals the line amount and the top-up reference contains the line's TransactionId.
• Possible users: candidates are scored from signals in the statement reference (phone number, wallet ID, names) and returned with their wallets.
• apply-topup: locks the wallet, rejects a duplicate reference, then writes the top-up and the ledger row manual_topup. It's audited, then the user is notified directly (SignalR balance update + push).
• requestpop: emails the customer for proof of payment.

13.18 Identity verification (KYC)

Request/response examples: §20.1 · §20.3

Two paths set Users.is_verified, which unlocks limits (§7.4).

1. Automatic (Didit)

• GET /api/auth/kyc/verification/start/{uid} returns a Didit session link.
• Didit's webhook is HMAC-checked, then DiditKycService (idempotent per session) compares Didit's result with the profile:
  • ID number against the document or personal number;
  • date of birth;
  • surname similarity ≥ 90% (required);
  • first names exact or ≥ 80% similar.
• It always stores a UserKycs row: document number and type, face-match and liveness scores, status, and the full raw Didit payload.
• Outcomes:

• The user is told through SignalR (UserUpdated).

2. Manual (documents)

• The user uploads ID documents (S3, 5 MB, allow-listed types, ClamAV scan).
• An admin approves: every document must be Uploaded, then is_verified = true and need_review = false.
• An admin rejects: the document becomes Rejected, is_verified = false, and the user is emailed the reason.
• unverify resets verification. Every action is audited.

Legacy: KYC_Profiles (/api/kyc) stores the ID number, status and ID document and selfie images as bytes in the database. It doesn't drive limits.

13.19 Notifications

Request/response examples: §20.10

Message texts are built in NotificationRepository.GenerateNotification, one per TransactionType.

13.20 Marketing campaigns and in-app content

Request/response examples: §20.10 · §20.11

• Who manages it: web-dashboard users (/api/admin/campaigns).
• Audiences: all users, selected users, filtered users (active, verified, roles, cities, created date range, last login range), or imported external contacts. External contacts come in batches with per-row issues and a suppression list; the public subscribe/unsubscribe endpoints manage the list.
• Scheduling: once, daily, weekly, monthly or yearly. Content is plain text or HTML, with media in S3.
• Statuses:
  • campaign: Draft → Queued → Active → Completed / PartiallyFailed / Failed / Cancelled;
  • run: Pending → Processing → WaitingForReceipts → done;
  • delivery: Pending / Sending / Sent / Failed / Retrying / Cancelled / PendingReceipt.
• Channels: only Push and Email are implemented. SMS, in-app pop-up, carousel and landing-page processors throw NotImplemented.
• Separate in-app content: display ads (/api/mobile/display-ads, with impression and click events) and website/app pop-up messages (/api/WebsitePopUpMessages).

13.21 POS terminals

Request/response examples: §20.1

POST /api/auth/terminal/session (anonymous) logs a merchant's POS terminal into their business account:

1. The terminal sends a session JWT minted by the POS service with the same JWT_SecretKey, with claims serialnumber (must equal the body's SN) and merchantId (= the owner's ID number).
2. Known merchant: the device in the request is bound alongside the owner's phone (deleteDevice: false, the phone stays linked), and app tokens are returned.
3. Unknown merchant: details are fetched from Terminal:BootstrapUrl (default: the hard-coded test service https://zakhaa-test-service.us-east-1.elasticbeanstalk.com/api/vas/user/details), with the token in the query string, and the business user is created locally.

13.22 Accounts, devices and wallet IDs

Request/response examples: §20.3 · §20.4

• Wallet IDs are 10-digit numbers:
  • created into the file Zakhaa Pay ZakhaaIDs.txt (POST /api/wallet/generate/{count}, non-cryptographic random);
  • imported into WalletIDs (/import);
  • allocated in order on wallet creation (first unassigned, then marked assigned).
• Pay@ account number = 13010 + wallet ID (the barcode from /pay-at-barcode).
• One active device per user: binding a new device deactivates the old one (IsActive=false, IsDelete=true).
• Account deletion is soft: is_active=false, is_deleted=true, Deleted_At. Data is kept.
• Suspension (admin) toggles is_active. Login rejects inactive users, with a "frozen, pending review" message when need_review is set.
• App version gate: AppSettings keys LatestAppVersion, ForceUpdate, UpdateUrlAndroid, UpdateUrlIOS → GET /api/settings/version.
• KPI page: GET /api/user/users (staff only) renders an HTML dashboard of business metrics: total and new users, daily and monthly active users, and volumes per rail.

14. Testing and local development

14.1 The test project

tests/WalletApi.Gateway.Tests (xUnit) runs the real app in memory (ApiFactory, a WebApplicationFactory) against a real PostgreSQL. About 200 tests in these suites:

14.2 Running the tests

DB-backed tests ([PgFact]) need PostgreSQL in GATEWAY_TEST_PG and are skipped without it. To use a throw-away local server:

initdb -D /tmp/pg -U postgres --auth=trust
pg_ctl -D /tmp/pg -o "-p 55491 -k /tmp -c listen_addresses=127.0.0.1" start
GATEWAY_TEST_PG="Host=127.0.0.1;Port=55491;Username=postgres" dotnet test tests/WalletApi.Gateway.Tests
pg_ctl -D /tmp/pg stop

How the test app is set up:

• ApiFactory sets dummy secrets (JWT, EncryptionKey, S3, ClamAV …) and runs as Development.
• It removes all hosted services, so background jobs don't run. A test that needs queued work runs it by hand (IBackgroundTaskQueue.DequeueAsync).
• Outside services (IEftCorpClient, notifications) are replaced with fakes in each test class.

One test is skipped on purpose (the public rate limiter, which depends on timing).

14.3 Running the API locally

1. Create appsettings.Development.json with a Config section holding every SecretKeys value (§3.2), using UAT or local values. It's git-ignored.
2. Run dotnet run. Swagger is at /swagger and seed data is created at startup.
3. App endpoints need a bound device (§6.2). It's usually easier to test them through the mobile app pointed at your machine, or to call repositories directly from a test.

15. Endpoint index

Every endpoint, sorted by path (without the /v2 base). Auth: S = Strict (JWT + device), D = Device only, J = any JWT, A = Admin/SuperAdmin, AS = admin+support (SuperAdmin, Admin, SupportAdmin), SA = SuperAdmin only, W = WebJwt, M = merchant API key, P:x = partner token with scope x, GA = gateway/refund/cash-device admin (SuperAdmin, Admin), — = none or own verification. § = section with details.

16. Security status and operational considerations

16.1 Open issues

Reviewed Nov 2026 after the security fixes (§16.2). Each needs an owner.

16.2 Fixed in Nov 2026

16.3 Operational gotchas

• Migrations are manual (§3.5). Everything up to RefundWebhookToken is applied in production.
• deploy-V2.sh runs docker volume prune -f, which deletes volumes not attached to a running container. uat-deploy.sh deliberately doesn't.
• Wallet.balance is a cache. Fix balances through the ledger, never by editing balance.
• HTTP 200 doesn't mean success on older endpoints: check success in the body.
• The device signature uses the path without /v2. A client that signs /v2/api/... gets "Invalid device signature".
• EFT Corp must get a 200 within 45 seconds on /api/stp/callback, or it reverses the payment. Processing is queued for this reason; keep the synchronous part small.
• EFT Corp REVERSED can mean a failed reversal: only bankResponse == "00" means it happened. Reversals we didn't request still claw back regardless (an OPS: warning is logged).
• Debit cards can't be refunded through doRefund (error 445). Only a full same-day reversal works.
• Rand vs cents: older endpoints use decimal rand; the gateway, refunds, cash devices and Flash requests use integer cents.
• SAST: daily limits, the trust-tier job and same-day reversals use Africa/Johannesburg.
• Disabled controllers: AmlController, CardController and DisputeController are commented out. AnalyticsController, CashoutController, PublicController and ServiceController have no actions.
• Don't roll back below Nov 2026: PIN hashes are upgraded at login (§6.4).
• Logs starting OPS: need a human: unconfirmed refunds, odd EFT Corp states, failed payment notifications.

17. How data is handled

17.1 What personal and financial data we store, and how

17.2 Third parties that receive data

17.3 Retention and deletion

• Users: soft-deleted (is_deleted, Deleted_At). Nothing is purged automatically.
• Devices: soft-deleted when replaced or unlinked.
• Financial records (Topups, Withdrawal, ledger, rail tables) are never deleted by the app.
• Vouchers expire after a year and are refunded by SetExpiredAsync.
• OTPs and device challenges expire from memory after 5 minutes. Device replay protection keeps request IDs for 10 minutes.

17.4 Balances and money rules (summary)

See §7. In short:

• the ledger is the source of truth and Wallet.balance is a cache;
• debits lock the wallet and check limits, tiers, holds and (for reserve-based rails) the fraud model;
• fees carry 15% VAT;
• the daily and monthly counters reset daily and monthly (SAST).

Two places still compute from the cached balance or skip the ledger: the Send Zakhaa receiver credit (opening balance from Wallet.balance) and the promo credit (no ledger row).

18. Configuration reference

All non-secret settings, from appsettings.{Environment}.json. Override any of them with an environment variable using __ for : (for example EftCorp__BaseUrl). Secrets are in §3.2.

Constants in code (not configurable):

• CheckoutRules.PortalOrigin = https://pay.zakhaapay.com (the checkout page);
• the HTTP base addresses in HttpClientExtensions (PayShap and CashSend middleware https://payshap.zakhaapay.com/, Zapper https://zapper.zakhaapay.com/, Didit, the fraud model);
• Pay@ limits R10–R15,000;
• trust-tier caps and hold durations (§7.4–7.5);
• the OTP lifetime (5 minutes) and attempt limit (5).

19. Operations runbook

Common tasks, with the exact endpoint or table to use. Paths are shown without /v2. "Admin token" means an admin JWT from /api/admin-auth/login with the role shown.

19.1 Customers

19.2 Money

19.3 Payment gateway (merchants)

19.4 Partners and access

19.5 App and platform

20. Request and response examples (every endpoint)

Every endpoint, with what it does, links to its reference table (§12) and the flow that explains it (§13, or §6 for sign-in), its permissions, parameters, an example request body and an example successful response. Endpoints are grouped by area and sorted by path; search for the path (for example cashsend/initiate) to jump to one.

20.0 How to read these examples

How the examples were produced. They're generated from the code: request bodies from the actual request classes, and responses from the declared result types or the method that produces the data. Responses that couldn't be traced automatically were checked by hand. The values are illustrative ("…" means any value of that type); the keys and structure are what the code uses.

JSON naming.

• Controllers and the feature slices read and write JSON with Newtonsoft.Json.
• Response keys are camelCase versions of the C# property names (PIN → pin, VAT → vat, ExpoPushToken → expoPushToken). Names that already contain underscores, such as wallet_id, are kept as they are.
• Request keys are matched case-insensitively against the C# property names.
• [JsonPropertyName] attributes are ignored, because they belong to System.Text.Json. Only Newtonsoft's [JsonProperty] renames a key. For example, the Flash request property AmountInCents carries [JsonPropertyName("amount")], but the key the API actually binds is amountInCents.

Paths. Paths are shown without the path base; prefix them with /v2 in production (§3.1).

Auth labels:

The four response shapes you'll see:

// 1. ServerResponse: older app endpoints. Often HTTP 200 even on failure, so check "success".
{ "success": true, "message": "", "data": { … } }
{ "success": false, "message": "Invalid OTP", "data": null }

// 2. Result<T>: newer endpoints, gateway, refunds, cash devices. Proper HTTP status codes.
{ "isSuccess": true, "data": { … }, "error": null }
{ "isSuccess": false, "data": null, "error": { "code": "validation_error", "description": "…", "metadata": null } }

// 3. Dictionary: VAS, Zapper, Scan to Pay payments
{ "success": true, "data": { … } }
{ "success": false, "message": "…" }

// 4. A bare object or list (some older GET endpoints)

Paged lists (page, pageSize → …):

{ "items": [ … ], "totalRecords": 120, "totalPages": 6, "currentPage": 1, "pageSize": 20, "hasNextPage": true, "hasPreviousPage": false }

Errors common to every endpoint:

Gateway-specific error codes are listed in docs/merchant-integration-guide.md §9 and docs/admin-dashboard-gateway.md.

20.1 Auth, devices and POS terminals

POST /api/auth/device/bind

What it does: Binds a phone to the user after checking the OTP that login emailed (keyed by the device ID). Registers the device's RSA public key, deactivates the user's previous device and pushes "Device unlinked" to it, then returns tokens and the full user data. The store-review account can use 256789 when Otp:AllowTestAccounts is on.

See: §12.1 · §6.4

Auth: None; rate limit auth

Request (DeviceRegisterDTO):

{
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "deviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "publicKey": "…",
  "otp": "482913",
  "deviceType": "Payment",
  "model": "…",
  "os": "…",
  "brand": "…",
  "localVersion": "…"
}

Response 200:

{
  "success": true,
  "message": "<expo push token>",
  "data": {
    "user": {
      "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Thandi",
      "surname": "Mokoena",
      "phone": "0821234567",
      "expoPushToken": "<token>",
      "idNumber": "9001015009087",
      "email": "thandi@example.com",
      "dob": "…",
      "roleId": 1,
      "is_verified": true,
      "needs_Review": true,
      "createdAt": "2026-11-11T08:30:00Z",
      "isActive": true
    },
    "accessToken": "<token>",
    "refreshToken": "<token>",
    "wallet": {
      "wallet_id": "9471452626",
      "balance": 150.00,
      "availableBalance": 150.00,
      "dailySpent": 1.00,
      "currency": "ZAR",
      "status": "Completed",
      "transactions": [ { … } ],
      "vouchers": [ { … } ]
    },
    "businesses": [{
      "name": "Thandi",
      "busID": "…",
      "wallet": {
        "wallet_id": "9471452626",
        "balance": 150.00,
        "availableBalance": 150.00,
        "dailySpent": 1.00,
        "currency": "ZAR",
        "status": "Completed",
        "transactions": [ { … } ],
        "vouchers": [ { … } ]
      },
      "isVerified": true,
      "streetAddress": "…",
      "suburb": "Braamfontein",
      "city": "Johannesburg",
      "province": "Gauteng",
      "postalCode": "2001",
      "mcc": "…",
      "type": "Payment",
      "email": "thandi@example.com"
    }],
    "transactions": [{
      "id": 1,
      "title": "Send Zakhaa",
      "wallet_id": "9471452626",
      "type": "Payment",
      "fee": 2.30,
      "vat": 0.35,
      "sender_id": "…",
      "receiver_id": "8312045577",
      "amount": 150.00,
      "tipAmount": 0.00,
      "failureReason": null,
      "method": "Send Zakhaa",
      "reference": "Rent share",
      "transaction_id": "…",
      "status": "Completed",
      "create_at": "2026-11-11T08:30:00Z"
    }],
    "additionalData": { },
    "notificationPreference": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "globalOptIn": true,
      "smsEnabled": true,
      "pushEnabled": true,
      "emailEnabled": true,
      "inAppEnabled": true,
      "systemEnabled": true,
      "marketingEnabled": true,
      "promotionsEnabled": true,
      "remindersEnabled": true,
      "createdAt": "2026-11-11T08:30:00Z",
      "updatedAt": "2026-11-11T08:30:00Z"
    }
  }
}

POST /api/auth/device/challenge

What it does: First step of signing in on an already-bound phone. For PIN sign-in it re-checks the PIN; it then returns a random 32-byte challenge (cached 5 minutes) for the device to sign. Failed attempts are logged in AuthenticationInfo.

See: §12.1 · §6.4

Auth: Device signature; rate limit auth

Request (DeviceLoginDTO):

{
  "deviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "authType": "Payment",
  "pin": "1234"
}

Response 200:

{
  "success": true,
  "message": "",
  "data": …
}

GET /api/auth/device/status/{DeviceId}

What it does: Tells the app whether this device is currently linked to an account (isLinked).

See: §12.1 · §6.4

Auth: None

Route: DeviceId (string)

Response 200:

{
  "success": true,
  "message": "",
  "data": { "isLinked": … }
}

POST /api/auth/device/unlink

What it does: Soft-deletes the calling device's binding (IsActive=false, IsDelete=true). The user must bind again with an OTP.

See: §12.1 · §6.4

Auth: Device signature

Response 200:

{
  "success": true,
  "message": "",
  "data": null
}

POST /api/auth/device/verify

What it does: Second step of signing in on a bound phone: verifies the RSA signature of the challenge, updates the app version and last-seen time, and returns tokens and the full user data.

See: §12.1 · §6.4

Auth: Device signature; rate limit auth

Request (DeviceVerifyDTO):

{
  "deviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "authType": "Payment",
  "signedChallenge": "…",
  "localVersion": "…"
}

Response 200:

{
  "success": true,
  "message": "<expo push token>",
  "data": {
    "user": {
      "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Thandi",
      "surname": "Mokoena",
      "phone": "0821234567",
      "expoPushToken": "<token>",
      "idNumber": "9001015009087",
      "email": "thandi@example.com",
      "dob": "…",
      "roleId": 1,
      "is_verified": true,
      "needs_Review": true,
      "createdAt": "2026-11-11T08:30:00Z",
      "isActive": true
    },
    "accessToken": "<token>",
    "refreshToken": "<token>",
    "wallet": {
      "wallet_id": "9471452626",
      "balance": 150.00,
      "availableBalance": 150.00,
      "dailySpent": 1.00,
      "currency": "ZAR",
      "status": "Completed",
      "transactions": [ { … } ],
      "vouchers": [ { … } ]
    },
    "businesses": [{
      "name": "Thandi",
      "busID": "…",
      "wallet": {
        "wallet_id": "9471452626",
        "balance": 150.00,
        "availableBalance": 150.00,
        "dailySpent": 1.00,
        "currency": "ZAR",
        "status": "Completed",
        "transactions": [ { … } ],
        "vouchers": [ { … } ]
      },
      "isVerified": true,
      "streetAddress": "…",
      "suburb": "Braamfontein",
      "city": "Johannesburg",
      "province": "Gauteng",
      "postalCode": "2001",
      "mcc": "…",
      "type": "Payment",
      "email": "thandi@example.com"
    }],
    "transactions": [{
      "id": 1,
      "title": "Send Zakhaa",
      "wallet_id": "9471452626",
      "type": "Payment",
      "fee": 2.30,
      "vat": 0.35,
      "sender_id": "…",
      "receiver_id": "8312045577",
      "amount": 150.00,
      "tipAmount": 0.00,
      "failureReason": null,
      "method": "Send Zakhaa",
      "reference": "Rent share",
      "transaction_id": "…",
      "status": "Completed",
      "create_at": "2026-11-11T08:30:00Z"
    }],
    "additionalData": { },
    "notificationPreference": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "globalOptIn": true,
      "smsEnabled": true,
      "pushEnabled": true,
      "emailEnabled": true,
      "inAppEnabled": true,
      "systemEnabled": true,
      "marketingEnabled": true,
      "promotionsEnabled": true,
      "remindersEnabled": true,
      "createdAt": "2026-11-11T08:30:00Z",
      "updatedAt": "2026-11-11T08:30:00Z"
    }
  }
}

GET /api/auth/kyc/verification/start/{uid}

What it does: Creates a Didit identity-verification session for the user and returns its link (13.18).

See: §12.1 · §13.18

Auth: Strict (user JWT + device signature)

Route: uid (string)

Response 200:

{
  "success": true,
  "message": "",
  "data": "…"
}

POST /api/auth/kyc/verification/webhook

What it does: Didit's result callback. HMAC-checked; approved results are matched against the profile (ID number, date of birth, names) and set is_verified, or freeze the account on a mismatch (13.18).

See: §12.1 · §13.18

Auth: None

Response 200: empty body.

POST /api/auth/login

What it does: Checks the phone number and PIN, then emails a device-verification OTP keyed by deviceId. No token is issued here; the app continues with device/bind. Same error message for an unknown number or a wrong PIN.

See: §12.1 · §6.4

Auth: None; rate limit auth

Request (LoginDTO):

{
  "phone_number": "0821234567",
  "password": "••••••",
  "deviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Response 200:

{
  "success": true,
  "message": "OTP sent successfully.",
  "data": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

POST /api/auth/otp

What it does: Sends an OTP by email for registration (EmailVerification), device verification, forgot-password or profile changes. Returns the user's ID (used by the app in later steps).

See: §12.1 · §6.4

Auth: None; rate limit auth

Request (OTPRequest):

{
  "userID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "thandi@example.com",
  "phone": "0821234567",
  "emailType": "OtpVerification"
}

Response 200:

{
  "success": true,
  "message": "",
  "data": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

POST /api/auth/register

What it does: Registers a personal user: checks the PIN rules and the OTP, creates the user, a personal wallet (next free Zakhaa ID), settings and notification preferences in one transaction, applies an optional promo credit, binds the device and returns tokens.

See: §12.1 · §6.4

Auth: None; rate limit auth

Request (RegisterDTO):

{
  "name": "Thandi",
  "surname": "Mokoena",
  "email": "thandi@example.com",
  "phone_number": "0821234567",
  "password": "••••••",
  "idNumber": "9001015009087",
  "promoCode": "<code>",
  "dob": "…",
  "idType": "Payment",
  "uid": "…",
  "otp": "482913",
  "latitude": 1.00,
  "longitude": 1.00,
  "deviceInfo": {
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "publicKey": "…",
    "otp": "482913",
    "deviceType": "Payment",
    "model": "…",
    "os": "…",
    "brand": "…",
    "localVersion": "…"
  }
}

Response 200:

{
  "success": true,
  "message": "",
  "data": {
    "user": {
      "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Thandi",
      "surname": "Mokoena",
      "phone": "0821234567",
      "expoPushToken": "<token>",
      "idNumber": "9001015009087",
      "email": "thandi@example.com",
      "dob": "…",
      "roleId": 1,
      "is_verified": true,
      "needs_Review": true,
      "createdAt": "2026-11-11T08:30:00Z",
      "isActive": true
    },
    "accessToken": "<token>",
    "refreshToken": "<token>",
    "wallet": {
      "wallet_id": "9471452626",
      "balance": 150.00,
      "availableBalance": 150.00,
      "dailySpent": 1.00,
      "currency": "ZAR",
      "status": "Completed",
      "transactions": [ { … } ],
      "vouchers": [ { … } ]
    },
    "businesses": [{
      "name": "Thandi",
      "busID": "…",
      "wallet": {
        "wallet_id": "9471452626",
        "balance": 150.00,
        "availableBalance": 150.00,
        "dailySpent": 1.00,
        "currency": "ZAR",
        "status": "Completed",
        "transactions": [ { … } ],
        "vouchers": [ { … } ]
      },
      "isVerified": true,
      "streetAddress": "…",
      "suburb": "Braamfontein",
      "city": "Johannesburg",
      "province": "Gauteng",
      "postalCode": "2001",
      "mcc": "…",
      "type": "Payment",
      "email": "thandi@example.com"
    }],
    "transactions": [{
      "id": 1,
      "title": "Send Zakhaa",
      "wallet_id": "9471452626",
      "type": "Payment",
      "fee": 2.30,
      "vat": 0.35,
      "sender_id": "…",
      "receiver_id": "8312045577",
      "amount": 150.00,
      "tipAmount": 0.00,
      "failureReason": null,
      "method": "Send Zakhaa",
      "reference": "Rent share",
      "transaction_id": "…",
      "status": "Completed",
      "create_at": "2026-11-11T08:30:00Z"
    }],
    "additionalData": { },
    "notificationPreference": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "globalOptIn": true,
      "smsEnabled": true,
      "pushEnabled": true,
      "emailEnabled": true,
      "inAppEnabled": true,
      "systemEnabled": true,
      "marketingEnabled": true,
      "promotionsEnabled": true,
      "remindersEnabled": true,
      "createdAt": "2026-11-11T08:30:00Z",
      "updatedAt": "2026-11-11T08:30:00Z"
    }
  }
}

POST /api/auth/register/business

What it does: Same as register, plus a Business row and a separate business wallet.

See: §12.1 · §6.4

Auth: None; rate limit auth

Request (RegisterBusinessDTO):

{
  "name": "Thandi",
  "surname": "Mokoena",
  "email": "thandi@example.com",
  "phone_number": "0821234567",
  "password": "••••••",
  "idNumber": "9001015009087",
  "businessName": "Thandi",
  "businessRegNumber": "…",
  "businessType": "Payment",
  "idType": "Payment",
  "businessCategory": "…",
  "dob": "…",
  "latitude": 1.00,
  "longitude": 1.00,
  "uid": "…",
  "otp": "482913",
  "promoCode": "<code>",
  "deviceInfo": {
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "publicKey": "…",
    "otp": "482913",
    "deviceType": "Payment",
    "model": "…",
    "os": "…",
    "brand": "…",
    "localVersion": "…"
  }
}

Response 200:

{
  "success": true,
  "message": "",
  "data": {
    "user": {
      "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Thandi",
      "surname": "Mokoena",
      "phone": "0821234567",
      "expoPushToken": "<token>",
      "idNumber": "9001015009087",
      "email": "thandi@example.com",
      "dob": "…",
      "roleId": 1,
      "is_verified": true,
      "needs_Review": true,
      "createdAt": "2026-11-11T08:30:00Z",
      "isActive": true
    },
    "accessToken": "<token>",
    "refreshToken": "<token>",
    "wallet": {
      "wallet_id": "9471452626",
      "balance": 150.00,
      "availableBalance": 150.00,
      "dailySpent": 1.00,
      "currency": "ZAR",
      "status": "Completed",
      "transactions": [ { … } ],
      "vouchers": [ { … } ]
    },
    "businesses": [{
      "name": "Thandi",
      "busID": "…",
      "wallet": {
        "wallet_id": "9471452626",
        "balance": 150.00,
        "availableBalance": 150.00,
        "dailySpent": 1.00,
        "currency": "ZAR",
        "status": "Completed",
        "transactions": [ { … } ],
        "vouchers": [ { … } ]
      },
      "isVerified": true,
      "streetAddress": "…",
      "suburb": "Braamfontein",
      "city": "Johannesburg",
      "province": "Gauteng",
      "postalCode": "2001",
      "mcc": "…",
      "type": "Payment",
      "email": "thandi@example.com"
    }],
    "transactions": [{
      "id": 1,
      "title": "Send Zakhaa",
      "wallet_id": "9471452626",
      "type": "Payment",
      "fee": 2.30,
      "vat": 0.35,
      "sender_id": "…",
      "receiver_id": "8312045577",
      "amount": 150.00,
      "tipAmount": 0.00,
      "failureReason": null,
      "method": "Send Zakhaa",
      "reference": "Rent share",
      "transaction_id": "…",
      "status": "Completed",
      "create_at": "2026-11-11T08:30:00Z"
    }],
    "additionalData": { },
    "notificationPreference": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "globalOptIn": true,
      "smsEnabled": true,
      "pushEnabled": true,
      "emailEnabled": true,
      "inAppEnabled": true,
      "systemEnabled": true,
      "marketingEnabled": true,
      "promotionsEnabled": true,
      "remindersEnabled": true,
      "createdAt": "2026-11-11T08:30:00Z",
      "updatedAt": "2026-11-11T08:30:00Z"
    }
  }
}

POST /api/auth/terminal/session

What it does: Signs a merchant's POS terminal into their business account using a session JWT from the POS service (serial number and merchant ID claims). Unknown merchants are fetched from Terminal:BootstrapUrl and created (13.21).

See: §12.1 · §13.21

Auth: None

Request (SessionDto):

{
  "sessionToken": "<token>",
  "sn": "…",
  "device": {
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "publicKey": "…",
    "otp": "482913",
    "deviceType": "Payment",
    "model": "…",
    "os": "…",
    "brand": "…",
    "localVersion": "…"
  }
}

Response 200:

{
  "success": true,
  "message": "success",
  "data": {
    "user": {
      "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Thandi",
      "surname": "Mokoena",
      "phone": "0821234567",
      "expoPushToken": "<token>",
      "idNumber": "9001015009087",
      "email": "thandi@example.com",
      "dob": "…",
      "roleId": 1,
      "is_verified": true,
      "needs_Review": true,
      "createdAt": "2026-11-11T08:30:00Z",
      "isActive": true
    },
    "accessToken": "<token>",
    "refreshToken": "<token>",
    "wallet": {
      "wallet_id": "9471452626",
      "balance": 150.00,
      "availableBalance": 150.00,
      "dailySpent": 1.00,
      "currency": "ZAR",
      "status": "Completed",
      "transactions": [ { … } ],
      "vouchers": [ { … } ]
    },
    "businesses": [{
      "name": "Thandi",
      "busID": "…",
      "wallet": {
        "wallet_id": "9471452626",
        "balance": 150.00,
        "availableBalance": 150.00,
        "dailySpent": 1.00,
        "currency": "ZAR",
        "status": "Completed",
        "transactions": [ { … } ],
        "vouchers": [ { … } ]
      },
      "isVerified": true,
      "streetAddress": "…",
      "suburb": "Braamfontein",
      "city": "Johannesburg",
      "province": "Gauteng",
      "postalCode": "2001",
      "mcc": "…",
      "type": "Payment",
      "email": "thandi@example.com"
    }],
    "transactions": [{
      "id": 1,
      "title": "Send Zakhaa",
      "wallet_id": "9471452626",
      "type": "Payment",
      "fee": 2.30,
      "vat": 0.35,
      "sender_id": "…",
      "receiver_id": "8312045577",
      "amount": 150.00,
      "tipAmount": 0.00,
      "failureReason": null,
      "method": "Send Zakhaa",
      "reference": "Rent share",
      "transaction_id": "…",
      "status": "Completed",
      "create_at": "2026-11-11T08:30:00Z"
    }],
    "additionalData": { },
    "notificationPreference": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "globalOptIn": true,
      "smsEnabled": true,
      "pushEnabled": true,
      "emailEnabled": true,
      "inAppEnabled": true,
      "systemEnabled": true,
      "marketingEnabled": true,
      "promotionsEnabled": true,
      "remindersEnabled": true,
      "createdAt": "2026-11-11T08:30:00Z",
      "updatedAt": "2026-11-11T08:30:00Z"
    }
  }
}

20.2 Admin authentication, admins, partner clients and audit

POST /api/admin-auth/2fa/enable

What it does: Confirms an admin's first TOTP code with the 10-minute setup token, turns two-factor login on and returns one-time recovery codes (shown once, stored hashed).

See: §12.2 · §6.5

Auth: None; rate limit auth

Request (TwoFactorEnableDto):

{
  "email": "thandi@example.com",
  "setupToken": "<token>",
  "code": "<code>"
}

Response 200:

{
  "isSuccess": true,
  "data": {
    "recoveryCodes": "…"
  },
  "error": null
}

POST /api/admin-auth/2fa/setup

What it does: Starts two-factor enrolment for an admin who got 428 TwoFactorSetupRequired at login: creates the TOTP key (stored encrypted) and returns it for the authenticator app.

See: §12.2 · §6.5

Auth: None

Request (TwoFactorSetupRequestDto):

{
  "email": "thandi@example.com",
  "password": "••••••"
}

Response 200:

{
  "isSuccess": true,
  "data": {
    "sharedKey": "…",
    "authenticatorUri": "…",
    "setupToken": "<token>"
  },
  "error": null
}

POST /api/admin-auth/change-password

What it does: Changes the logged-in admin's password (Identity rules). Audited.

See: §12.2 · §6.5

Auth: Any JWT

Request (ChangeAdminPasswordDto):

{
  "currentPassword": "••••••",
  "newPassword": "••••••"
}

Response 200:

{
  "isSuccess": true,
  "data": "…",
  "error": null
}

POST /api/admin-auth/forgot-password

What it does: Emails the admin a password-reset link. Audited.

See: §12.2 · §6.5

Auth: None; rate limit auth

Request (ForgotPasswordDto):

{
  "email": "thandi@example.com"
}

Response 200:

{
  "isSuccess": true,
  "data": "…",
  "error": null
}

POST /api/admin-auth/login

What it does: Admin sign-in: password check with lockout (5 failures → 15 minutes, 423), mandatory TOTP or recovery code, then an access token in the body and a rotated refresh token in the refreshToken cookie.

See: §12.2 · §6.5

Auth: None; rate limit auth

Request (LoginAdminDto):

{
  "email": "thandi@example.com",
  "password": "••••••",
  "twoFactorCode": "<code>",
  "recoveryCode": "<code>"
}

Response 200:

{
  "isSuccess": true,
  "data": {
    "accessToken": "<token>",
    "refreshToken": "<token>",
    "passwordInitialChange": true,
    "twoFactorEnabled": true
  },
  "error": null
}

POST /api/admin-auth/logout

What it does: Ends the admin session (revokes the refresh token, clears the cookie).

See: §12.2 · §6.5

Auth: None

Response 204: no content.

POST /api/admin-auth/refresh

What it does: Exchanges the refreshToken cookie for a new access token, rotating the refresh token (the old one is revoked).

See: §12.2 · §6.5

Auth: None

Response 200:

{
  "isSuccess": true,
  "data": {
    "accessToken": "<token>",
    "refreshToken": "<token>",
    "passwordInitialChange": true,
    "twoFactorEnabled": true
  },
  "error": null
}

POST /api/admin-auth/register

What it does: Creates a new admin account (Identity user + Admins row) and emails them. Audited.

See: §12.2 · §6.5

Auth: Roles: Admin, SuperAdmin

Request (RegisterAdminDto):

{
  "email": "thandi@example.com",
  "contactNumber": "…",
  "firstName": "Thandi",
  "lastName": "Thandi",
  "role": "…",
  "password": "••••••",
  "department": "…"
}

Response 200:

{
  "isSuccess": true,
  "data": {
    "id": "…",
    "firstName": "Thandi",
    "lastName": "Thandi",
    "email": "thandi@example.com",
    "contactNumber": "…",
    "department": "…",
    "lastLoginUtc": "2026-11-11T08:30:00Z",
    "createdAtUtc": "2026-11-11T08:30:00Z",
    "updatedAtUtc": "2026-11-11T08:30:00Z",
    "passwordInitialChange": true,
    "isActive": true,
    "roles": "…"
  },
  "error": null
}

POST /api/admin-auth/reset-password

What it does: Sets a new admin password using the token from the reset email. Audited.

See: §12.2 · §6.5

Auth: None; rate limit auth

Request (ResetPasswordDto):

{
  "email": "thandi@example.com",
  "newPassword": "••••••",
  "token": "<token>"
}

Response 200:

{
  "isSuccess": true,
  "data": "…",
  "error": null
}

POST /api/admin-auth/unlock-account

What it does: Clears an admin's lockout. Audited.

See: §12.2 · §6.5

Auth: Roles: Admin, SuperAdmin

Request (UnlockAdminAccountDto):

{
  "email": "thandi@example.com"
}

Response 200:

{
  "isSuccess": true,
  "data": "…",
  "error": null
}

GET /api/admin/all

What it does: Lists admins with their roles (includeInactive to show deactivated ones).

See: §12.2

Auth: Roles: Admin, SuperAdmin

Query: includeInactive (bool)

Response 200:

{
  "isSuccess": true,
  "data": [
    {
      "id": "…",
      "firstName": "Thandi",
      "lastName": "Thandi",
      "email": "thandi@example.com",
      "contactNumber": "…",
      "department": "…",
      "isActive": true,
      "lastLoginUtc": "2026-11-11T08:30:00Z",
      "roles": "…"
    }
  ],
  "error": null
}

GET /api/admin/me/{id}

What it does: Returns an admin profile by Identity ID: your own, or anyone's for a SuperAdmin.

See: §12.2

Auth: Any JWT

Route: id (string)

Response 200:

{
  "isSuccess": true,
  "data": {
    "id": "…",
    "firstName": "Thandi",
    "lastName": "Thandi",
    "email": "thandi@example.com",
    "contactNumber": "…",
    "department": "…"
  },
  "error": null
}

GET /api/admin/{id}

What it does: Returns one admin.

See: §12.2

Auth: Roles: Admin, SuperAdmin

Route: id (string)

Response 200:

{
  "isSuccess": true,
  "data": {
    "id": "…",
    "firstName": "Thandi",
    "lastName": "Thandi",
    "email": "thandi@example.com",
    "contactNumber": "…",
    "department": "…",
    "lastLoginUtc": "2026-11-11T08:30:00Z",
    "createdAtUtc": "2026-11-11T08:30:00Z",
    "updatedAtUtc": "2026-11-11T08:30:00Z",
    "passwordInitialChange": true,
    "isActive": true,
    "roles": "…"
  },
  "error": null
}

DELETE /api/admin/{id}/delete

What it does: Deletes an admin account.

See: §12.2

Auth: Roles: SuperAdmin

Route: id (string)

Response 200:

{
  "isSuccess": true,
  "data": "…",
  "error": null
}

PUT /api/admin/{id}/role

What it does: Replaces an admin's role.

See: §12.2

Auth: Roles: SuperAdmin

Route: id (string)

Request (UpdateAdminRoleDto):

{
  "role": "…"
}

Response 200:

{
  "isSuccess": true,
  "data": "…",
  "error": null
}

PUT /api/admin/{id}/status

What it does: Activates or deactivates an admin.

See: §12.2

Auth: Roles: SuperAdmin

Route: id (string)

Request (UpdateAdminStatusDto):

{
  "isActive": true
}

Response 200:

{
  "isSuccess": true,
  "data": true,
  "error": null
}

PUT /api/admin/{id}/update

What it does: Updates an admin's profile (name, email/username): your own, or anyone's for a SuperAdmin.

See: §12.2

Auth: Any JWT

Route: id (string)

Request (UpdateAdminDto):

{
  "firstName": "Thandi",
  "lastName": "Thandi",
  "email": "thandi@example.com",
  "contactNumber": "…",
  "department": "…"
}

Response 200:

{
  "isSuccess": true,
  "data": {
    "id": "…",
    "firstName": "Thandi",
    "lastName": "Thandi",
    "email": "thandi@example.com",
    "contactNumber": "…",
    "department": "…",
    "lastLoginUtc": "2026-11-11T08:30:00Z",
    "createdAtUtc": "2026-11-11T08:30:00Z",
    "updatedAtUtc": "2026-11-11T08:30:00Z",
    "passwordInitialChange": true,
    "isActive": true,
    "roles": "…"
  },
  "error": null
}

POST /api/client-auth/token

What it does: Partner token endpoint (OAuth client credentials). Verifies the BCrypt-hashed secret, revokes the client's other active tokens (except Pay@), records the new token's jti and returns a JWT carrying the client's scope.

See: §12.11 · §6.6

Auth: None; rate limit auth

Body: application/x-www-form-urlencoded with client_id, client_secret, grant_type, scope.

Response 200:

{
  "isSuccess": true,
  "data": {
    "accessToken": "<token>",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "scope": "…"
  },
  "error": null
}

GET /api/admin/api-clients

What it does: Lists partner API clients.

See: §12.11 · §6.6

Auth: Roles: SuperAdmin

Response 200:

{
  "isSuccess": true,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "clientId": "…",
      "name": "Thandi",
      "scope": "…",
      "status": "Completed",
      "tokenLifetimeSeconds": 3600,
      "createdAt": "2026-11-11T08:30:00Z"
    }
  ],
  "error": null
}

POST /api/admin/api-clients

What it does: Registers a partner client (ID, secret, name, scope, token lifetime). The secret is stored as a BCrypt hash.

See: §12.11 · §6.6

Auth: Roles: SuperAdmin

Request (RegisterApiClientRequest):

{
  "clientId": "…",
  "clientSecret": "…",
  "name": "Thandi",
  "scope": "…",
  "tokenLifetimeSeconds": 3600
}

Response 200:

{
  "isSuccess": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "clientId": "…",
    "clientSecret": "…",
    "name": "Thandi",
    "scope": "…",
    "createdAt": "2026-11-11T08:30:00Z"
  },
  "error": null
}

PATCH /api/admin/api-clients/{clientId}/activate

What it does: Re-enables a suspended partner client.

See: §12.11 · §6.6

Auth: Roles: SuperAdmin

Route: clientId (string)

Response 200:

{
  "isSuccess": true,
  "data": "…",
  "error": null
}

PATCH /api/admin/api-clients/{clientId}/revoke-tokens

What it does: Revokes every active token of a partner client immediately.

See: §12.11 · §6.6

Auth: Roles: SuperAdmin

Route: clientId (string)

Response 200:

{
  "isSuccess": true,
  "data": "…",
  "error": null
}

PATCH /api/admin/api-clients/{clientId}/rotate-secret

What it does: Generates a new client secret (shown once).

See: §12.11 · §6.6

Auth: Roles: SuperAdmin

Route: clientId (string)

Response 200:

{
  "isSuccess": true,
  "data": {
    "clientId": "…",
    "newSecret": "…"
  },
  "error": null
}

PATCH /api/admin/api-clients/{clientId}/suspend

What it does: Suspends a partner client so it can't get tokens.

See: §12.11 · §6.6

Auth: Roles: SuperAdmin

Route: clientId (string)

Response 200:

{
  "isSuccess": true,
  "data": "…",
  "error": null
}

GET /api/audit

What it does: Lists the admin audit log (who did what, to which record).

See: §12.4

Auth: Roles: Admin, SuperAdmin

Response 200:

{
  "isSuccess": true,
  "data": [
    {
      "auditLogId": 1,
      "adminId": "…",
      "adminFirstName": "Thandi",
      "adminLastName": "Thandi",
      "adminEmail": "thandi@example.com",
      "action": "…",
      "description": "…",
      "targetType": "Payment",
      "targetId": "…",
      "timestamp": "2026-11-11T08:30:00Z"
    }
  ],
  "error": null
}

GET /api/audit/{id}

What it does: Audit entries of one admin.

See: §12.4

Auth: Roles: Admin, SuperAdmin

Route: id (string)

Response 200:

{
  "isSuccess": true,
  "data": [
    {
      "auditLogId": 1,
      "adminId": "…",
      "adminFirstName": "Thandi",
      "adminLastName": "Thandi",
      "adminEmail": "thandi@example.com",
      "action": "…",
      "description": "…",
      "targetType": "Payment",
      "targetId": "…",
      "timestamp": "2026-11-11T08:30:00Z"
    }
  ],
  "error": null
}

20.3 Users, KYC, documents, notes and addresses

POST /api/user/add/business

What it does: Adds a business and its business wallet to the logged-in user's account.

See: §12.3 · §13.22

Auth: Strict (user JWT + device signature)

Request (AddBusinessDTO):

{
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "businessName": "Thandi",
  "businessRegNumber": "…",
  "businessType": "Payment",
  "businessEmail": "thandi@example.com",
  "businessCategory": "…"
}

Response 200:

{
  "success": true,
  "message": "",
  "data": {
    "user": {
      "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Thandi",
      "surname": "Mokoena",
      "phone": "0821234567",
      "expoPushToken": "<token>",
      "idNumber": "9001015009087",
      "email": "thandi@example.com",
      "dob": "…",
      "roleId": 1,
      "is_verified": true,
      "needs_Review": true,
      "createdAt": "2026-11-11T08:30:00Z",
      "isActive": true
    },
    "accessToken": "<token>",
    "refreshToken": "<token>",
    "wallet": {
      "wallet_id": "9471452626",
      "balance": 150.00,
      "availableBalance": 150.00,
      "dailySpent": 1.00,
      "currency": "ZAR",
      "status": "Completed",
      "transactions": [ { … } ],
      "vouchers": [ { … } ]
    },
    "businesses": [{
      "name": "Thandi",
      "busID": "…",
      "wallet": {
        "wallet_id": "9471452626",
        "balance": 150.00,
        "availableBalance": 150.00,
        "dailySpent": 1.00,
        "currency": "ZAR",
        "status": "Completed",
        "transactions": [ { … } ],
        "vouchers": [ { … } ]
      },
      "isVerified": true,
      "streetAddress": "…",
      "suburb": "Braamfontein",
      "city": "Johannesburg",
      "province": "Gauteng",
      "postalCode": "2001",
      "mcc": "…",
      "type": "Payment",
      "email": "thandi@example.com"
    }],
    "transactions": [{
      "id": 1,
      "title": "Send Zakhaa",
      "wallet_id": "9471452626",
      "type": "Payment",
      "fee": 2.30,
      "vat": 0.35,
      "sender_id": "…",
      "receiver_id": "8312045577",
      "amount": 150.00,
      "tipAmount": 0.00,
      "failureReason": null,
      "method": "Send Zakhaa",
      "reference": "Rent share",
      "transaction_id": "…",
      "status": "Completed",
      "create_at": "2026-11-11T08:30:00Z"
    }],
    "additionalData": { },
    "notificationPreference": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "globalOptIn": true,
      "smsEnabled": true,
      "pushEnabled": true,
      "emailEnabled": true,
      "inAppEnabled": true,
      "systemEnabled": true,
      "marketingEnabled": true,
      "promotionsEnabled": true,
      "remindersEnabled": true,
      "createdAt": "2026-11-11T08:30:00Z",
      "updatedAt": "2026-11-11T08:30:00Z"
    }
  }
}

GET /api/user/all

What it does: Dashboard user list, searchable and paged: wallet, contact details, KYC (is_verified) and status.

See: §12.3 · §13.22

Auth: Roles: SuperAdmin, Admin, SupportAdmin, Sales

Query: search (string?), page (int), pageSize (int)

Response 200:

{
  "isSuccess": true,
  "data": {
    "items": [
      {
        "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "walletId": "9471452626",
        "name": "Thandi",
        "phone": "0821234567",
        "email": "thandi@example.com",
        "balance": 150.00,
        "kyc": true,
        "status": true
      }
    ],
    "totalRecords": 1,
    "totalPages": 1,
    "currentPage": 1,
    "pageSize": 20,
    "hasNextPage": false,
    "hasPreviousPage": false
  },
  "error": null
}

POST /api/user/confirm

What it does: Confirms the user's PIN (used before account deletion).

See: §12.3 · §13.22

Auth: Strict (user JWT + device signature)

Request (DeleteDto):

{
  "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "password": "••••••"
}

Response 200:

{
  "success": true,
  "message": "",
  "data": true
}

DELETE /api/user/delete/{uid}

What it does: Soft-deletes the caller's own account (is_active=false, is_deleted=true) and emails a confirmation.

See: §12.3 · §13.22

Auth: Strict (user JWT + device signature)

Route: uid (Guid)

Response 200:

{
  "success": true,
  "message": "",
  "data": null
}

GET /api/user/nfc/tags/{walletId}

What it does: Staff view of a wallet's NFC tags (not pending ones).

See: §12.3 · §13.22

Auth: Roles: SuperAdmin, Admin, SupportAdmin, Sales

Route: walletId (string)

Response 200:

{
  "isSuccess": true,
  "data": [
    {
      "tagId": "tg_9f3k2m",
      "status": "Completed",
      "createdAt": "2026-11-11T08:30:00Z",
      "revokedAt": "2026-11-11T08:30:00Z"
    }
  ],
  "error": null
}

GET /api/user/unverified/Users

What it does: Users who haven't completed KYC, searchable (including ID number).

See: §12.3 · §13.22

Auth: Roles: SuperAdmin, Admin, SupportAdmin, Sales

Query: search (string?), page (int), pageSize (int)

Response 200:

{
  "isSuccess": true,
  "data": {
    "items": [
      {
        "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "idNumber": "9001015009087",
        "name": "Thandi",
        "phone": "0821234567",
        "email": "thandi@example.com",
        "kyc": true
      }
    ],
    "totalRecords": 1,
    "totalPages": 1,
    "currentPage": 1,
    "pageSize": 20,
    "hasNextPage": false,
    "hasPreviousPage": false
  },
  "error": null
}

PUT /api/user/update/email/{userId}

What it does: Changes the user's email after verifying the OTP.

See: §12.3 · §13.22

Auth: Strict (user JWT + device signature)

Route: userId (Guid)

Request (DetailsUpdateDto):

{
  "value": "true",
  "otp": "482913",
  "email": "thandi@example.com"
}

Response 200:

{
  "success": true,
  "message": "…",
  "data": { }
}

PUT /api/user/update/password/{userId}

What it does: Changes the user's PIN after verifying the OTP (stored with PBKDF2).

See: §12.3 · §13.22

Auth: Strict (user JWT + device signature)

Route: userId (Guid)

Request (DetailsUpdateDto):

{
  "value": "true",
  "otp": "482913",
  "email": "thandi@example.com"
}

Response 200:

{
  "success": true,
  "message": "…",
  "data": { }
}

PUT /api/user/update/phone/{userId}

What it does: Changes the user's phone number after verifying the OTP.

See: §12.3 · §13.22

Auth: Strict (user JWT + device signature)

Route: userId (Guid)

Request (DetailsUpdateDto):

{
  "value": "true",
  "otp": "482913",
  "email": "thandi@example.com"
}

Response 200:

{
  "success": true,
  "message": "…",
  "data": { }
}

POST /api/user/updateotp

What it does: Emails an OTP for a profile change (email, phone or PIN).

See: §12.3 · §13.22

Auth: Strict (user JWT + device signature); rate limit auth

Request (UserUpdateDto):

{
  "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "Payment",
  "email": "thandi@example.com",
  "phone": "0821234567",
  "password": "••••••"
}

Response 200:

{
  "success": true,
  "message": "",
  "data": true
}

PUT /api/user/updatesignin/{userId}

What it does: Forgot-PIN flow: verifies the OTP and sets a new PIN.

See: §12.3 · §13.22

Auth: None; rate limit auth

Route: userId (Guid)

Request (UpdateRequestDto):

{
  "type": "Payment",
  "email": "thandi@example.com",
  "phone": "0821234567",
  "password": "••••••",
  "emailOTP": "…",
  "phoneOTP": "…"
}

Response 200:

{
  "success": true,
  "message": "…",
  "data": { }
}

POST /api/user/upload/{filepath}

What it does: Maintenance: bulk-creates verified users with wallets from ./test.csv and emails them passwords.

See: §12.3 · §13.22

Auth: Roles: SuperAdmin

Route: filePath (string)

Response 200:

[
  {
    "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Thandi",
    "surname": "Mokoena",
    "phone": "0821234567",
    "expoPushToken": "<token>",
    "idNumber": "9001015009087",
    "email": "thandi@example.com",
    "dob": "…",
    "roleId": 1,
    "is_verified": true,
    "needs_Review": true,
    "createdAt": "2026-11-11T08:30:00Z",
    "isActive": true
  }
]

GET /api/user/users

What it does: HTML dashboard of business KPIs: users, active users and daily/monthly volumes per rail.

See: §12.3 · §13.22

Auth: Roles: SuperAdmin, Admin, SupportAdmin

Query: date (DateTime?)

Response 200: an HTML page (text/html).

GET /api/user/{userId}

What it does: Full user detail for staff: profile, wallets and business names.

See: §12.3 · §13.22

Auth: Roles: SuperAdmin, Admin, SupportAdmin, Sales

Route: userId (Guid)

Response 200:

{
  "isSuccess": true,
  "data": {
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Thandi",
    "phone": "0821234567",
    "email": "thandi@example.com",
    "kyc": true,
    "status": true,
    "mainAccount": {
      "accountType": "Payment",
      "walletId": "9471452626",
      "busId": "…",
      "businessName": "Thandi",
      "balance": 150.00,
      "currency": "ZAR",
      "status": "Completed"
    },
    "accounts": [{
      "accountType": "Payment",
      "walletId": "9471452626",
      "busId": "…",
      "businessName": "Thandi",
      "balance": 150.00,
      "currency": "ZAR",
      "status": "Completed"
    }]
  },
  "error": null
}

PUT /api/user/{userId}

What it does: Staff edit of a user's name, phone or email (checked for uniqueness).

See: §12.3 · §13.22

Auth: Roles: SuperAdmin, Admin, SupportAdmin, Sales

Route: userId (Guid)

Request (UpdateUserProfileDto):

{
  "name": "Thandi",
  "phone": "0821234567",
  "email": "thandi@example.com"
}

Response 200:

{
  "isSuccess": true,
  "data": {
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Thandi",
    "phone": "0821234567",
    "email": "thandi@example.com"
  },
  "error": null
}

GET /api/user/{userId}/accounts/{walletId}/transactions

What it does: Paged transactions of one of the user's wallets.

See: §12.3 · §13.22

Auth: Roles: SuperAdmin, Admin, SupportAdmin, Sales

Route: userId (Guid), walletId (string)

Query: page (int), pageSize (int)

Response 200:

{
  "isSuccess": true,
  "data": {
    "items": [
      {
        "id": 1,
        "title": "Send Zakhaa",
        "wallet_id": "9471452626",
        "type": "Payment",
        "fee": 2.30,
        "vat": 0.35,
        "sender_id": "…",
        "receiver_id": "8312045577",
        "amount": 150.00,
        "tipAmount": 0.00,
        "failureReason": null,
        "method": "Send Zakhaa",
        "reference": "Rent share",
        "transaction_id": "…",
        "status": "Completed",
        "create_at": "2026-11-11T08:30:00Z"
      }
    ],
    "totalRecords": 1,
    "totalPages": 1,
    "currentPage": 1,
    "pageSize": 20,
    "hasNextPage": false,
    "hasPreviousPage": false
  },
  "error": null
}

GET /api/user/{userId}/analytics

What it does: Totals from the ledger for the user's wallets (spent, received, average monthly spend).

See: §12.3 · §13.22

Auth: Roles: SuperAdmin, Admin, SupportAdmin, Sales

Route: userId (Guid)

Response 200:

{
  "isSuccess": true,
  "data": {
    "totalSpent": 1.00,
    "totalReceived": 1.00,
    "averageMonthlySpend": 1.00,
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "walletCount": 1,
    "totalBalance": 150.00
  },
  "error": null
}

PUT /api/user/{userId}/reactivate

What it does: Reactivates a suspended or frozen user (is_active=true). Audited.

See: §12.3 · §13.22

Auth: Roles: SuperAdmin, Admin, SupportAdmin

Route: userId (Guid)

Response 200:

{
  "isSuccess": true,
  "data": { "userId": …, "status": … },
  "error": null
}

PUT /api/user/{userId}/suspend

What it does: Suspends a user (is_active=false); they can no longer log in. Audited.

See: §12.3 · §13.22

Auth: Roles: SuperAdmin, Admin, SupportAdmin

Route: userId (Guid)

Response 200:

{
  "isSuccess": true,
  "data": {
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": false
  },
  "error": null
}

GET /api/kyc/getbyid/{id}

What it does: Returns one of the caller's legacy KYC profiles.

See: §12.3 · §13.18

Auth: Strict (user JWT + device signature)

Route: id (int)

Response 200:

{
  "profile_id": 1,
  "idNumber": "9001015009087",
  "id_type": "Payment",
  "id_doc": "…",
  "selfie": "…",
  "kyc_status": "Completed",
  "selfietype": "Payment",
  "iddoctype": "Payment",
  "verified_at": "2026-11-11T08:30:00Z",
  "created_at": "2026-11-11T08:30:00Z"
}

GET /api/kyc/getbyuid{uid}

What it does: Returns the caller's legacy KYC profile.

See: §12.3 · §13.18

Auth: Strict (user JWT + device signature)

Route: uid (Guid)

Response 200:

{
  "profile_id": 1,
  "idNumber": "9001015009087",
  "id_type": "Payment",
  "id_doc": "…",
  "selfie": "…",
  "kyc_status": "Completed",
  "selfietype": "Payment",
  "iddoctype": "Payment",
  "verified_at": "2026-11-11T08:30:00Z",
  "created_at": "2026-11-11T08:30:00Z"
}

POST /api/kyc/kyc

What it does: Creates a legacy KYC profile for the caller (ID number, ID document and selfie as base64). Always starts pending.

See: §12.3 · §13.18

Auth: Strict (user JWT + device signature)

Request (CreateKYCDto):

{
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "idNumber": "9001015009087",
  "id_type": "Payment",
  "id_doc": "…",
  "selfie": "…",
  "kyc_status": "Completed",
  "verified_at": "2026-11-11T08:30:00Z",
  "created_at": "2026-11-11T08:30:00Z"
}

Response 200:

{
  "profile_id": 1,
  "idNumber": "9001015009087",
  "id_type": "Payment",
  "id_doc": "…",
  "selfie": "…",
  "kyc_status": "Completed",
  "selfietype": "Payment",
  "iddoctype": "Payment",
  "verified_at": "2026-11-11T08:30:00Z",
  "created_at": "2026-11-11T08:30:00Z"
}

DELETE /api/kyc/{id}

What it does: Deletes one of the caller's legacy KYC profiles.

See: §12.3 · §13.18

Auth: Strict (user JWT + device signature)

Route: id (int)

Response 200:

{
  "profile_id": 1,
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "idNumber": "9001015009087",
  "id_type": "Payment",
  "id_doc": "<base64>",
  "selfie": "<base64>",
  "kyc_status": "Completed",
  "verified_at": "2026-11-11T08:30:00Z",
  "created_at": "2026-11-11T08:30:00Z",
  "user": {
    "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Thandi",
    "surname": "Mokoena",
    "email": "thandi@example.com",
    "idType": "Payment",
    "idNumber": "9001015009087",
    "expoPushToken": "<token>",
    "phone": "0821234567",
    "password": "••••••",
    "roleId": 1,
    "salt": "…",
    "is_verified": true,
    "is_active": true,
    "need_review": true,
    "is_deleted": true,
    "created_at": "2026-11-11T08:30:00Z",
    "updated_at": "2026-11-11T08:30:00Z",
    "deleted_At": "2026-11-11T08:30:00Z",
    "last_Login": "2026-11-11T08:30:00Z",
    "location": "…",
    "postal_code": "<code>",
    "dob": "…",
    "emailStatus": true,
    "phoneStatus": true,
    "addresses": [ { … } ],
    "kyC_Profile": {
      "profile_id": 1,
      "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "idNumber": "9001015009087",
      "id_type": "Payment",
      "id_doc": "<base64>",
      "selfie": "<base64>",
      "kyc_status": "Completed",
      "verified_at": "2026-11-11T08:30:00Z",
      "created_at": "2026-11-11T08:30:00Z",
      "user": { … }
    },
    "amL_Flags": [ { … } ],
    "wallets": [ { … } ],
    "cards": [ { … } ],
    "kins": [ { … } ],
    "settings": {
      "settingId": 1,
      "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "notifyOn": true,
      "darkMode": true,
      "notifyOnTransaction": true,
      "notifyOnKycStatus": true,
      "enableTwoFactorAuth": true,
      "preferredLanguage": "…",
      "updatedAt": "2026-11-11T08:30:00Z",
      "user": { … }
    },
    "devices": [ { … } ],
    "notifications": [ { … } ],
    "notificationPreference": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "user": { … },
      "globalOptIn": true,
      "smsEnabled": true,
      "pushEnabled": true,
      "emailEnabled": true,
      "inAppEnabled": true,
      "systemEnabled": true,
      "marketingEnabled": true,
      "promotionsEnabled": true,
      "remindersEnabled": true,
      "createdAt": "2026-11-11T08:30:00Z",
      "updatedAt": "2026-11-11T08:30:00Z"
    },
    "documents": [ { … } ],
    "businesses": [ { … } ],
    "zakhaaVouchers": [ { … } ],
    "userActivities": [ { … } ],
    "selectedUsers": [ { … } ],
    "recipients": [ { … } ],
    "displayAdEvents": [ { … } ],
    "userNotes": [ { … } ]
  }
}

PATCH /api/kyc/{id}

What it does: Updates the caller's legacy KYC profile (ID number, images). The status can't be changed by the user.

See: §12.3 · §13.18

Auth: Strict (user JWT + device signature)

Route: id (int)

Request (PutKYCDto):

{
  "idNumber": "9001015009087",
  "id_doc": "…",
  "selfie": "…",
  "kyc_status": "Completed",
  "verified_at": "2026-11-11T08:30:00Z"
}

Response 200:

{
  "profile_id": 1,
  "idNumber": "9001015009087",
  "id_type": "Payment",
  "id_doc": "…",
  "selfie": "…",
  "kyc_status": "Completed",
  "selfietype": "Payment",
  "iddoctype": "Payment",
  "verified_at": "2026-11-11T08:30:00Z",
  "created_at": "2026-11-11T08:30:00Z"
}

GET /api/documents/{userId}

What it does: Lists a user's KYC documents (metadata; files are in S3).

See: §12.3 · §13.18

Auth: Any JWT

Route: userId (Guid)

Response 200:

{
  "isSuccess": true,
  "data": [
    {
      "documentId": 1,
      "originalFileName": "Thandi",
      "documentType": "Payment",
      "status": "Completed",
      "uploadedAt": "2026-11-11T08:30:00Z",
      "updatedAt": "2026-11-11T08:30:00Z",
      "downloadUrl": "…",
      "previewUrl": "…"
    }
  ],
  "error": null
}

POST /api/documents/{userId}

What it does: Uploads a KYC document: max 5 MB, allow-listed types, virus-scanned by ClamAV, stored in S3.

See: §12.3 · §13.18

Auth: Any JWT

Route: userId (Guid)

Query: fileName (string?), documentType (string?)

Body: multipart/form-data with a file field.

Response 200:

{
  "isSuccess": true,
  "data": {
    "documentId": 1,
    "originalFileName": "Thandi",
    "s3Key": "…",
    "documentType": "Payment",
    "status": "Completed",
    "downloadUrl": "…"
  },
  "error": null
}

DELETE /api/documents/{userId}/{documentId}

What it does: Deletes a KYC document (S3 object and metadata).

See: §12.3 · §13.18

Auth: Any JWT

Route: userId (Guid), documentId (long)

Response 200:

{
  "isSuccess": true,
  "data": {
    "documentId": 1,
    "s3Key": "…",
    "status": "Completed"
  },
  "error": null
}

POST /api/documents/{userId}/approve

What it does: Approves a user's KYC documents (all must be Uploaded) and sets is_verified=true. Audited.

See: §12.3 · §13.18

Auth: Roles: SuperAdmin, Admin, SupportAdmin

Route: userId (Guid)

Response 200:

{
  "isSuccess": true,
  "data": {
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "isVerified": true,
    "approvedDocuments": 1,
    "approvedAtUtc": "2026-11-11T08:30:00Z"
  },
  "error": null
}

POST /api/documents/{userId}/reject

What it does: Rejects one document with a reason, sets is_verified=false and emails the user. Audited.

See: §12.3 · §13.18

Auth: Roles: SuperAdmin, Admin, SupportAdmin

Route: userId (Guid)

Request (RejectDocumentRequest):

{
  "documentId": 1,
  "userEmail": "thandi@example.com",
  "reason": "Customer request"
}

Response 200:

{
  "isSuccess": true,
  "data": {
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "documentId": 1,
    "userEmail": "thandi@example.com",
    "reason": "Customer request",
    "emailSent": true
  },
  "error": null
}

POST /api/documents/{userId}/unverify

What it does: Removes a user's verified status. Audited.

See: §12.3 · §13.18

Auth: Roles: SuperAdmin, Admin, SupportAdmin

Route: userId (Guid)

Response 200:

{
  "isSuccess": true,
  "data": {
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "wasVerified": true,
    "isVerified": true,
    "needReview": true,
    "unverifiedAtUtc": "2026-11-11T08:30:00Z"
  },
  "error": null
}

GET /api/notes/user/{userId}

What it does: Internal staff notes on a user.

See: §12.3

Auth: Roles: SuperAdmin, Admin, SupportAdmin

Route: userId (Guid)

Response 200:

{
  "isSuccess": true,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "adminId": "…",
      "actionType": "Payment",
      "status": "Completed",
      "reason": "Customer request",
      "createdAtUtc": "2026-11-11T08:30:00Z",
      "updatedAtUtc": "2026-11-11T08:30:00Z"
    }
  ],
  "error": null
}

POST /api/notes/user/{userId}

What it does: Adds an internal note (with a status) to a user. Audited.

See: §12.3

Auth: Roles: SuperAdmin, Admin, SupportAdmin

Route: userId (Guid)

Request (CreateUserNoteDto):

{
  "actionType": "Payment",
  "status": "Completed",
  "reason": "Customer request"
}

Response 200:

{
  "isSuccess": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "adminId": "…",
    "actionType": "Payment",
    "status": "Completed",
    "reason": "Customer request",
    "createdAtUtc": "2026-11-11T08:30:00Z",
    "updatedAtUtc": "2026-11-11T08:30:00Z"
  },
  "error": null
}

PUT /api/notes/{noteId}

What it does: Edits an internal note. Audited.

See: §12.3

Auth: Roles: SuperAdmin, Admin, SupportAdmin

Route: noteId (Guid)

Request (UpdateUserNoteDto):

{
  "actionType": "Payment",
  "status": "Completed",
  "reason": "Customer request"
}

Response 200:

{
  "isSuccess": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "adminId": "…",
    "actionType": "Payment",
    "status": "Completed",
    "reason": "Customer request",
    "createdAtUtc": "2026-11-11T08:30:00Z",
    "updatedAtUtc": "2026-11-11T08:30:00Z"
  },
  "error": null
}

POST /api/address

What it does: Adds an address to the caller's profile.

See: §12.3 · §13.22

Auth: Strict (user JWT + device signature)

Request (CreateAddressDto):

{
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "street": "12 Main Rd",
  "suburb": "Braamfontein",
  "city": "Johannesburg",
  "province": "Gauteng",
  "postalCode": "2001",
  "country": "South Africa",
  "type": "Payment",
  "isVerified": true
}

Response 200:

{
  "address_id": 1,
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "street": "12 Main Rd",
  "suburb": "Braamfontein",
  "city": "Johannesburg",
  "province": "Gauteng",
  "postalCode": "2001",
  "country": "South Africa",
  "type": "Payment",
  "isVerified": true,
  "user": {
    "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Thandi",
    "surname": "Mokoena",
    "email": "thandi@example.com",
    "idType": "Payment",
    "idNumber": "9001015009087",
    "expoPushToken": "<token>",
    "phone": "0821234567",
    "password": "••••••",
    "roleId": 1,
    "salt": "…",
    "is_verified": true,
    "is_active": true,
    "need_review": true,
    "is_deleted": true,
    "created_at": "2026-11-11T08:30:00Z",
    "updated_at": "2026-11-11T08:30:00Z",
    "deleted_At": "2026-11-11T08:30:00Z",
    "last_Login": "2026-11-11T08:30:00Z",
    "location": "…",
    "postal_code": "<code>",
    "dob": "…",
    "emailStatus": true,
    "phoneStatus": true,
    "addresses": [ { … } ],
    "kyC_Profile": {
      "profile_id": 1,
      "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "idNumber": "9001015009087",
      "id_type": "Payment",
      "id_doc": "<base64>",
      "selfie": "<base64>",
      "kyc_status": "Completed",
      "verified_at": "2026-11-11T08:30:00Z",
      "created_at": "2026-11-11T08:30:00Z",
      "user": { … }
    },
    "amL_Flags": [ { … } ],
    "wallets": [ { … } ],
    "cards": [ { … } ],
    "kins": [ { … } ],
    "settings": {
      "settingId": 1,
      "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "notifyOn": true,
      "darkMode": true,
      "notifyOnTransaction": true,
      "notifyOnKycStatus": true,
      "enableTwoFactorAuth": true,
      "preferredLanguage": "…",
      "updatedAt": "2026-11-11T08:30:00Z",
      "user": { … }
    },
    "devices": [ { … } ],
    "notifications": [ { … } ],
    "notificationPreference": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "user": { … },
      "globalOptIn": true,
      "smsEnabled": true,
      "pushEnabled": true,
      "emailEnabled": true,
      "inAppEnabled": true,
      "systemEnabled": true,
      "marketingEnabled": true,
      "promotionsEnabled": true,
      "remindersEnabled": true,
      "createdAt": "2026-11-11T08:30:00Z",
      "updatedAt": "2026-11-11T08:30:00Z"
    },
    "documents": [ { … } ],
    "businesses": [ { … } ],
    "zakhaaVouchers": [ { … } ],
    "userActivities": [ { … } ],
    "selectedUsers": [ { … } ],
    "recipients": [ { … } ],
    "displayAdEvents": [ { … } ],
    "userNotes": [ { … } ]
  }
}

GET /api/address/getall/{uid}

What it does: The caller's addresses.

See: §12.3 · §13.22

Auth: Strict (user JWT + device signature)

Route: uid (Guid)

Response 200:

[
  {
    "address_id": 1,
    "street": "12 Main Rd",
    "suburb": "Braamfontein",
    "city": "Johannesburg",
    "province": "Gauteng",
    "postalCode": "2001",
    "country": "South Africa",
    "type": "Payment",
    "isVerified": true
  }
]

GET /api/address/getbyid/{id}

What it does: One of the caller's addresses.

See: §12.3 · §13.22

Auth: Strict (user JWT + device signature)

Route: id (int)

Response 200:

{
  "address_id": 1,
  "street": "12 Main Rd",
  "suburb": "Braamfontein",
  "city": "Johannesburg",
  "province": "Gauteng",
  "postalCode": "2001",
  "country": "South Africa",
  "type": "Payment",
  "isVerified": true
}

DELETE /api/address/{id}

What it does: Deletes one of the caller's addresses.

See: §12.3 · §13.22

Auth: Strict (user JWT + device signature)

Route: id (int)

Response 200:

12

PUT /api/address/{id}

What it does: Updates one of the caller's addresses.

See: §12.3 · §13.22

Auth: Strict (user JWT + device signature)

Route: id (int)

Request (PutAddressDto):

{
  "street": "12 Main Rd",
  "suburb": "Braamfontein",
  "city": "Johannesburg",
  "province": "Gauteng",
  "postalCode": "2001",
  "country": "South Africa",
  "type": "Payment"
}

Response 200:

{
  "address_id": 1,
  "street": "12 Main Rd",
  "suburb": "Braamfontein",
  "city": "Johannesburg",
  "province": "Gauteng",
  "postalCode": "2001",
  "country": "South Africa",
  "type": "Payment",
  "isVerified": true
}

20.4 Wallets, top-ups, transactions, dashboard and helpdesk

POST /api/wallet

What it does: Manually creates a wallet (allocates the next free Zakhaa ID). Wallets are normally created at registration.

See: §12.4 · §13.22

Auth: Roles: SuperAdmin

Request (CreateWalletDto):

{
  "balance": 150.00,
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "currency": "ZAR",
  "status": "Completed",
  "updated_at": "2026-11-11T08:30:00Z",
  "created_at": "2026-11-11T08:30:00Z"
}

Response 200:

{
  "wallet_id": "9471452626",
  "balance": 150.00,
  "availableBalance": 150.00,
  "dailySpent": 1.00,
  "currency": "ZAR",
  "status": "Completed",
  "transactions": [{
    "id": 1,
    "title": "Send Zakhaa",
    "wallet_id": "9471452626",
    "type": "Payment",
    "fee": 2.30,
    "vat": 0.35,
    "sender_id": "…",
    "receiver_id": "8312045577",
    "amount": 150.00,
    "tipAmount": 0.00,
    "failureReason": null,
    "method": "Send Zakhaa",
    "reference": "Rent share",
    "transaction_id": "…",
    "status": "Completed",
    "create_at": "2026-11-11T08:30:00Z"
  }],
  "vouchers": [{
    "id": 1,
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "voucher": "483920175562",
    "pin": "1234",
    "walletId": "9471452626",
    "amount": 150.00,
    "fee": 2.30,
    "vat": 0.35,
    "redeemed": true,
    "reversed": true,
    "expired": true,
    "createdAt": "2026-11-11T08:30:00Z",
    "expiresAt": "2026-11-11T08:30:00Z",
    "reversedAt": "2026-11-11T08:30:00Z",
    "redeemedAt": "2026-11-11T08:30:00Z"
  }]
}

GET /api/wallet/analytics

What it does: Platform-wide totals from the ledger: total spent, total received, average monthly spend.

See: §12.4 · §13.22

Auth: Roles: SuperAdmin, Admin, SupportAdmin

Response 200:

{
  "isSuccess": true,
  "data": {
    "totalSpent": 1.00,
    "totalReceived": 1.00,
    "averageMonthlySpend": 1.00
  },
  "error": null
}

POST /api/wallet/generate/{count}

What it does: Generates random 10-digit Zakhaa IDs into the file Zakhaa Pay ZakhaaIDs.txt.

See: §12.4 · §13.22

Auth: Roles: SuperAdmin

Route: count (int)

Response 200: empty body.

POST /api/wallet/import

What it does: Imports the generated Zakhaa IDs into the WalletIDs pool (skips existing ones).

See: §12.4 · §13.22

Auth: Roles: SuperAdmin

Response 200:

{ "totalLinesInFile": …, "inserted": …, "skippedExisting": … }

DELETE /api/wallet/{id}

What it does: Deletes a wallet.

See: §12.4 · §13.22

Auth: Roles: SuperAdmin

Route: id (string)

Response 204: no content.

GET /api/wallet/{uid}

What it does: The caller's personal wallet.

See: §12.4 · §13.22

Auth: Strict (user JWT + device signature)

Route: uid (Guid)

Response 200:

{
  "wallet_id": "9471452626",
  "balance": 150.00,
  "availableBalance": 150.00,
  "dailySpent": 1.00,
  "currency": "ZAR",
  "status": "Completed",
  "transactions": [{
    "id": 1,
    "title": "Send Zakhaa",
    "wallet_id": "9471452626",
    "type": "Payment",
    "fee": 2.30,
    "vat": 0.35,
    "sender_id": "…",
    "receiver_id": "8312045577",
    "amount": 150.00,
    "tipAmount": 0.00,
    "failureReason": null,
    "method": "Send Zakhaa",
    "reference": "Rent share",
    "transaction_id": "…",
    "status": "Completed",
    "create_at": "2026-11-11T08:30:00Z"
  }],
  "vouchers": [{
    "id": 1,
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "voucher": "483920175562",
    "pin": "1234",
    "walletId": "9471452626",
    "amount": 150.00,
    "fee": 2.30,
    "vat": 0.35,
    "redeemed": true,
    "reversed": true,
    "expired": true,
    "createdAt": "2026-11-11T08:30:00Z",
    "expiresAt": "2026-11-11T08:30:00Z",
    "reversedAt": "2026-11-11T08:30:00Z",
    "redeemedAt": "2026-11-11T08:30:00Z"
  }]
}

GET /api/wallet/{walletId}

What it does: One of the caller's wallets: balance, available (spendable) balance, daily spend, status.

See: §12.4 · §13.22

Auth: Strict (user JWT + device signature)

Route: walletId (string)

Response 200:

{
  "wallet_id": "9471452626",
  "balance": 150.00,
  "availableBalance": 150.00,
  "dailySpent": 1.00,
  "currency": "ZAR",
  "status": "Completed",
  "transactions": [{
    "id": 1,
    "title": "Send Zakhaa",
    "wallet_id": "9471452626",
    "type": "Payment",
    "fee": 2.30,
    "vat": 0.35,
    "sender_id": "…",
    "receiver_id": "8312045577",
    "amount": 150.00,
    "tipAmount": 0.00,
    "failureReason": null,
    "method": "Send Zakhaa",
    "reference": "Rent share",
    "transaction_id": "…",
    "status": "Completed",
    "create_at": "2026-11-11T08:30:00Z"
  }],
  "vouchers": [{
    "id": 1,
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "voucher": "483920175562",
    "pin": "1234",
    "walletId": "9471452626",
    "amount": 150.00,
    "fee": 2.30,
    "vat": 0.35,
    "redeemed": true,
    "reversed": true,
    "expired": true,
    "createdAt": "2026-11-11T08:30:00Z",
    "expiresAt": "2026-11-11T08:30:00Z",
    "reversedAt": "2026-11-11T08:30:00Z",
    "redeemedAt": "2026-11-11T08:30:00Z"
  }]
}

GET /api/wallet/{walletId}/pay-at-barcode

What it does: Code 128 barcode (13010 + wallet ID) the customer shows at a Pay@ till to deposit cash.

See: §12.4 · §13.22

Auth: Strict (user JWT + device signature)

Route: walletId (string)

Response 200:

{
  "reference": "Rent share",
  "imageBase64": "…"
}

GET /api/topup/getbywallet/{walletid}

What it does: Completed credits (money in) of the caller's wallet.

See: §12.4 · §13.11

Auth: Strict (user JWT + device signature)

Route: walletid (string)

Response 200:

[
  {
    "topup_id": 1,
    "title": "Send Zakhaa",
    "sender_id": "…",
    "wallet_id": "9471452626",
    "amount": 150.00,
    "method": "Send Zakhaa",
    "reference": "Rent share",
    "status": "Completed",
    "create_at": "2026-11-11T08:30:00Z"
  }
]

POST /api/topup/top-up

What it does: Manual credit by a SuperAdmin: writes a Completed top-up, the ledger row and notifies the user. Audited.

See: §12.4 · §13.11

Auth: Roles: SuperAdmin

Request (CreateTopUpDto):

{
  "wallet_id": "9471452626",
  "sender_id": "…",
  "title": "Send Zakhaa",
  "amount": 150.00,
  "method": "Send Zakhaa",
  "reference": "Rent share",
  "status": "Completed",
  "create_at": "2026-11-11T08:30:00Z"
}

Response 200:

{
  "topup_id": 1,
  "title": "Send Zakhaa",
  "sender_id": "…",
  "wallet_id": "9471452626",
  "amount": 150.00,
  "method": "Send Zakhaa",
  "reference": "Rent share",
  "status": "Completed",
  "create_at": "2026-11-11T08:30:00Z"
}