Top-up & Reload Bonus

Overview

You top up a Feddi wallet in two steps: prepare moves no money, confirm credits the wallet. The cash goes to the merchant's bank at the gateway. Feddi credits the ledger only after confirm succeeds. Feddi never holds the money.

A top-up credits actual balance, the customer's real money. A reload bonus accrues in the same transaction as a promotional grant, a separate, lighter class that is locked, expirable, and clawback-able. The two classes never merge into one number. Read Money: Actual vs Promotional before you build this flow.

The two-step model

A top-up is split so that no wallet credit ever races a gateway payment.

Confirm is idempotent on the Idempotency-Key header and defensively deduped on the provider settlement reference (provider_payment_ref). A duplicate provider webhook plus a partner poll credit exactly once.

Prepare a top-up

POST /v1/partner/topup/prepare is Planned. It creates a provider session and returns the redirect or client artifact. The credited amount is server-authoritative: amount_minor and currency are the basis, and the partner never sets the final credited amount.

curl -X POST https://api.feddi.io/v1/partner/topup/prepare \
  -H "Authorization: Bearer $TERMINAL_JWT" \
  -H "Idempotency-Key: 8d2f6e10-2c4a-4f9b-9d1e-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{
    "meta": { "partner_request_id": "8d2f...", "occurred_at": "2026-06-05T09:12:00Z", "sent_at": "2026-06-05T09:12:01Z", "api_version": "2026-06-01" },
    "context": { "merchant_id": "1111...", "branch_id": "2222...", "terminal_id": "POS-360-0007", "cashier_id": "cashier-42", "partner_session_id": "ord-99812" },
    "customer": { "credential_type": "phone", "phone": "+97433001122" },
    "amount_minor": 5000,
    "currency": "QAR",
    "return_url": "https://pos.example.qa/topup/return"
  }'

{
  "ok": true,
  "data": {
    "provider": "SADAD",
    "currency": "QAR",
    "amount_minor": 5000,
    "session_ref": "sadad-sess-7f3a91",
    "redirect_url": "https://gw.sadad.qa/checkout/7f3a91",
    "expires_at": "2026-06-05T09:17:01Z"
  },
  "error": null,
  "meta": { "request_id": "req_a1b2c3", "idempotency_replayed": false, "api_version": "2026-06-01", "data_completeness_score": 62 }
}

Confirm a top-up

POST /v1/partner/topup/confirm is Beta. It credits actual balance and accrues the reload bonus, then publishes wallet.balance_changed, topup.confirmed, and promo_grant.accrued after the transaction commits.

The reload bonus accrues as a GATEWAY_BONUS grant. Because the customer is already identified at top-up time, that grant accrues RELEASED (no claim gate). The credited amount is derived from the finalized provider event, never from POS-submitted totals.

curl -X POST https://api.feddi.io/v1/partner/topup/confirm \
  -H "Authorization: Bearer $TERMINAL_JWT" \
  -H "Idempotency-Key: 9f01...-confirm" \
  -H "Content-Type: application/json" \
  -d '{
    "meta": { "partner_request_id": "f3a1...", "occurred_at": "2026-06-05T09:15:00Z", "sent_at": "2026-06-05T09:15:01Z", "api_version": "2026-06-01" },
    "context": { "merchant_id": "1111...", "branch_id": "2222...", "terminal_id": "POS-360-0007", "partner_session_id": "ord-99812" },
    "session_ref": "sadad-sess-7f3a91",
    "provider": "SADAD",
    "provider_payment_ref": "sadad-trans-0099812",
    "amount_minor": 5000,
    "currency": "QAR"
  }'

{
  "ok": true,
  "data": {
    "transaction_id": "tx_77c1",
    "status": "completed",
    "wallet_id": "wal_5512",
    "credited_minor": 5000,
    "bonus_minor": 500,
    "balance_after_minor": 12500,
    "promo_balance_after_minor": 500,
    "currency": "QAR",
    "reload_bonus": {
      "applied": true,
      "bonus_minor": 500,
      "promo_grant_id": "pg_aa01",
      "promo_grant_state": "released",
      "source": "GATEWAY_BONUS",
      "expires_at": "2026-09-05T00:00:00Z"
    }
  },
  "error": null,
  "meta": { "request_id": "req_c4d5", "idempotency_replayed": false, "api_version": "2026-06-01", "data_completeness_score": 70 }
}

Top up mid-checkout (insufficient-funds recovery)

When a wallet pay against a session fails with INSUFFICIENT_FUNDS, you do not dead-end the customer. You offer an inline reload anchored to the same checkout session.

POST /v1/partner/checkout/sessions/{id}/topup is Planned. It is the session-scoped equivalent of prepare then confirm: pass step: "prepare" for the gateway artifact, then step: "confirm" (or let the provider webhook confirm) to credit and accrue the bonus. The prepared top-up, the basket, the identity, and the recovery pay all attach to one telemetry anchor, so the Brain learns the recovery counterfactual.

The session must be OPEN or IDENTIFIED and owned by the calling integration. A cross-tenant session resolves to 403 or 404. Crediting an unverified PENDING_PROOF identity follows the same gate as the standalone flow: actual balance credits, cashback-class promo stays LOCKED. See The PENDING_PROOF Invariant.

Cashier-sold reloads (top-up SKUs)

Some merchants sell a reload as a line item at the till (for example a "QAR 50 wallet load" SKU). Register the SKU once, then report each sale.

POST /v1/partner/topup/sku-register is Planned. It registers a top-up SKU with its wallet_credits_minor and bonus configuration.

POST /v1/partner/topup/sku/{skuId} is Beta. The POS reports that a registered SKU was sold at tender. Feddi credits the wallet by the SKU's registered wallet_credits_minor and accrues any SKU bonus as a SKU_TOPUP_BONUS grant in the same transaction. The credited amount and bonus are derived server-side from the SKU registration and the finalized POS sale, never from POS-submitted money fields. The call is idempotent on the Idempotency-Key header and on the POS order reference (pos_order_ref), so a duplicate sale report never double-credits.

GET /v1/partner/topup/skus is Planned. It lists the registered SKUs for the cashier dropdown, tenant-scoped to your integration.

Configure the reload bonus

POST /v1/partner/topup/reload-bonus/config is Beta. It sets the amount-banded bonus a wallet program grants on a top-up (for example "top up QAR 50+, get 10% bonus").

Each tier is { min_topup_minor, max_topup_minor?, bonus_type (PERCENTAGE | FIXED_AMOUNT), bonus_value }. Tiers must not overlap and percentages stay within 0 to 100. Config is forward-looking only: it governs future top-ups and never re-grants retroactively. The bonus it produces is the merchant's deferred-revenue marketing liability, accrued as a PromoGrant, not Feddi-custodied money.

{
  "wallet_program_id": "wp_77",
  "currency": "QAR",
  "expiry_days": 90,
  "tiers": [
    { "min_topup_minor": 5000, "max_topup_minor": 9999, "bonus_type": "PERCENTAGE", "bonus_value": 10 },
    { "min_topup_minor": 10000, "max_topup_minor": null, "bonus_type": "PERCENTAGE", "bonus_value": 15 }
  ]
}

Read the balance

GET /v1/partner/wallet/{walletId}/balance is Planned. It returns both money classes: balance_minor (actual, cashable), promo_balance_minor (RELEASED, non-expired promotional credit), and pending_topup_minor (in-flight top-ups). Resolve the customer by wallet_id or by identity credential (phone or provider_customer_id) via query params. wallet_program_id is first-class in the response. If an identity resolves to multiple programs and none is specified, the call returns WALLET_PROGRAM_AMBIGUOUS listing the candidates. Cross-enterprise lookups resolve to NOT_FOUND so no PII leaks.

Poll an async top-up

GET /v1/partner/topup/status/{transactionId} is Planned. When the gateway confirm is asynchronous (a Sadad webhook), poll the status by transaction id or by the Idempotency-Key used at confirm. It returns pending, completed, or failed, plus the credited and bonus amounts once complete. The lookup is tenant-scoped with a 24h retention window.

Reverse a top-up

POST /v1/partner/topups/{id}/reverse is Planned and operator-gated for the pilot. It reverses a confirmed top-up (mistake, fraud, chargeback) and claws back any reload bonus it accrued, as a single idempotent compensation saga: debit the credited actual balance back out, claw back the associated PromoGrant(s), then attempt the provider refund.

Because promo may already be partially spent, the reversal resolves to one of three explicit terminal outcomes.

A double-reverse replays the original terminal outcome. This is a Tier 1 money path: build it last, and only behind an operator credential.

{
  "transaction_id": "tx_77c1",
  "outcome": "REVERSED_WITH_PROMO_LEAK",
  "reversed_minor": 5000,
  "bonus_clawed_back_minor": 200,
  "bonus_leaked_minor": 300,
  "provider_refund_status": "initiated",
  "balance_after_minor": 7500,
  "currency": "QAR"
}

Provider webhook and settlement (Planned)

POST /v1/partner/topup/webhook is Planned. It is the inbound completion webhook from the payment provider (Sadad). It is a separate contract from the outbound envelope: it carries no Idempotency-Key header, deduplicates on the provider settlement id (provider, provider_payment_ref) plus a transaction lock, verifies an RSA signature, filters by enterprise server-side before crediting, and returns the provider's literal ACK (Sadad expects success). It is not wrapped in the standard partner response shape.

Two phase-2 reconciliation surfaces are also Planned: POST /v1/partner/topup/settlement-report (ingest the provider's settlement report) and POST /v1/partner/topup/webhook/reconciliation (the inbound daily-settlement webhook). Neither is in day-1 scope.

Operations

Where to go next