Payments & Redemption

One endpoint debits the wallet

You debit a Feddi wallet with POST /v1/partner/payments. It is a first-class resource, not a side-effect of redeeming an offer. One call collects a customer credential, debits the balance atomically, and returns a PaymentResult that splits the debit into promo and actual money.

The debit is atomic and promo-first. Feddi spends released promotional credit first (FIFO by expiry), then real money, in a single transaction. The two parts always sum to the amount you asked for. If the combined balance cannot cover the amount, nothing is debited and the credential is not consumed, so you route to recovery and retry.

Operations

This table reflects the contract. Where this page and openapi.yaml disagree, the spec wins.

Most calls authenticate with the terminal-scoped JWT (PosTerminalJWT). The two integration-scoped operations, paymentGet and refundCreate, carry the integration x-api-key instead. The terminal-driven operations (paymentAuthorize, paymentCapture, qrMint, redeemBalanceCheck, redeemVoid) all use the terminal JWT. Refresh the terminal JWT before a money call: it has a 600s TTL. See Authentication.

Debit the wallet

POST /v1/partner/payments collects the credential, debits the balance, and returns the result in one round trip. Send the full envelope, an Idempotency-Key header, and a credential block discriminated on credential.type.

The credential is a discriminated union. Adding a new credential type is an enum extension plus a validator, never a new route.

curl -X POST https://api.feddi.io/v1/partner/payments \
  -H "Authorization: Bearer $TERMINAL_JWT" \
  -H "Idempotency-Key: a1b2c3d4-0001-0001-0001-000000000001" \
  -H "Content-Type: application/json" \
  -d '{
    "meta": {
      "partner_request_id": "a1b2c3d4-0001-0001-0001-000000000001",
      "occurred_at": "2026-06-05T10:00:00Z",
      "sent_at": "2026-06-05T10:00:01Z",
      "api_version": "2026-06-01"
    },
    "context": {
      "merchant_id": "11111111-1111-1111-1111-111111111111",
      "branch_id": "22222222-2222-2222-2222-222222222222",
      "terminal_id": "POS-360-0007",
      "cashier_id": "cashier-42",
      "partner_session_id": "ord-88812",
      "feddi_session_id": "33333333-3333-3333-3333-333333333333"
    },
    "credential": {
      "type": "otp",
      "phone": "+97433001122",
      "otp_code": "483921",
      "otp_session_id": "otps_cc01"
    },
    "amount_minor": 3402,
    "currency": "QAR",
    "order_ref": "ord-88812",
    "basket": {
      "lines": [
        { "sku": "COFFEE-001", "qty": 2, "unit_price_minor": 1500, "ext_price_minor": 3000 },
        { "sku": "PASTRY-007", "qty": 1, "unit_price_minor": 500, "ext_price_minor": 500 }
      ]
    }
  }'

{
  "meta": {
    "partner_request_id": "a1b2c3d4-0001-0001-0001-000000000001",
    "occurred_at": "2026-06-05T10:00:00Z",
    "sent_at": "2026-06-05T10:00:01Z",
    "api_version": "2026-06-01"
  },
  "context": {
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "branch_id": "22222222-2222-2222-2222-222222222222",
    "terminal_id": "POS-360-0007",
    "cashier_id": "cashier-42",
    "partner_session_id": "ord-88812",
    "feddi_session_id": "33333333-3333-3333-3333-333333333333"
  },
  "credential": {
    "type": "otp",
    "phone": "+97433001122",
    "otp_code": "483921",
    "otp_session_id": "otps_cc01"
  },
  "amount_minor": 3402,
  "currency": "QAR",
  "order_ref": "ord-88812",
  "basket": {
    "lines": [
      { "sku": "COFFEE-001", "qty": 2, "unit_price_minor": 1500, "ext_price_minor": 3000 },
      { "sku": "PASTRY-007", "qty": 1, "unit_price_minor": 500, "ext_price_minor": 500 }
    ]
  }
}

The PaymentResult

A successful debit returns a PaymentResult inside the standard envelope. The result splits the debit into debited_promo_minor and debited_actual_minor, and the two always sum to amount_minor.

{
  "ok": true,
  "data": {
    "payment_id": "pay_77c1",
    "status": "completed",
    "wallet_id": "wal_5512",
    "amount_minor": 3402,
    "debited_promo_minor": 500,
    "debited_actual_minor": 2902,
    "currency": "QAR",
    "order_ref": "ord-88812",
    "balance_after": {
      "actual_minor": 9500,
      "promo_available_minor": 0,
      "promo_locked_minor": 200,
      "pending_topups_minor": 0,
      "currency": "QAR",
      "promo_grants": []
    },
    "completed_at": "2026-06-05T10:00:01Z"
  },
  "error": null,
  "meta": {
    "request_id": "req_p1",
    "idempotency_replayed": false,
    "api_version": "2026-06-01",
    "data_completeness_score": 80
  }
}

v1 is a single atomic debit

In v1, a wallet payment is one atomic debit. There is no reservation, no held-money state, no AUTHORIZED balance you capture later. The ledger debits immediately and returns the result.

The two-phase authorize → capture flow (reserve funds without debiting, capture or release later) is a card-style pre-auth hold reserved for a future payment_mode: hold in v2. Do not build against a held-money state in v1: it does not exist yet.

The OTP second-leg (capture)

The OTP path can run in two legs when your POS separates credential collection from debit authorization. The first call mints and sends the OTP. The customer enters it on the PIN-pad. Then POST /v1/partner/payments/{id}/capture carries the OTP and authorizes the debit.

The action field discriminates the capture:

A capture returns the same PaymentResult with status: completed. A close returns status: voided. The call is idempotent on the Idempotency-Key header.

Mint a QR or short-code

When the customer pays from their wallet app, mint a rotating credential with POST /v1/partner/qr/mint, render the qr_payload as a QR code, and optionally display the short_code for manual entry. The POS then scans the QR and passes it back as credential.type: qr in POST /payments.

The nonce is bound to the customer's wallet with a five-minute TTL. Re-minting before the TTL expires invalidates the old nonce and returns a new one. The QR session is single-use: a replayed nonce in POST /payments returns CREDENTIAL_EXPIRED_OR_REPLAYED (400).

{
  "ok": true,
  "data": {
    "qr_session_id": "qrs_dd01",
    "qr_payload": "feddi://pay?nonce=eyJhbGciOiJFUzI1NiJ9...&wallet=wal_5512",
    "short_code": "A7X3Q",
    "expires_at": "2026-06-05T10:03:00Z",
    "ttl_seconds": 300
  },
  "error": null,
  "meta": { "request_id": "req_qr1", "idempotency_replayed": false, "api_version": "2026-06-01" }
}

Insufficient funds is a recovery path, not a dead end

When the wallet balance (actual plus released promo) cannot cover the amount, POST /payments returns INSUFFICIENT_FUNDS (402). Nothing is debited. The OTP or QR credential is not consumed, so the customer can retry after a reload. This is the highest-intent moment in the whole interaction: the customer wants to spend and cannot. Model it as a recovery path.

{
  "ok": false,
  "data": null,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Wallet balance is insufficient for this payment.",
    "details": {
      "shortfall_minor": 1200,
      "available_actual_minor": 1800,
      "available_promo_minor": 500,
      "currency": "QAR"
    }
  },
  "meta": { "request_id": "req_p2", "idempotency_replayed": false, "api_version": "2026-06-01" }
}

On INSUFFICIENT_FUNDS, offer an inline reload anchored to the same checkout session, then retry the debit. Read details.shortfall_minor to size the prompt. For the top-up mechanics, see Top-up & Reload Bonus.

PENDING_PROOF wallets may not pay

A PENDING_PROOF wallet is a proto-wallet that holds reloads but gates promo release and payment behind phone proof. A payment against one returns FORBIDDEN (403). Redirect the customer to enrollment to verify their phone, then retry. See Enrollment & Verification and The PENDING_PROOF Invariant.

Errors

Errors are typed string codes in error.code, never a bare HTTP number. Branch on the code and read error.details for the actionable fields.

The full set is in Error Reference.

Idempotency on the debit

Every POST /payments call carries an Idempotency-Key header. A retried call with the same key and same payload replays the original PaymentResult byte-identical with meta.idempotency_replayed: true: it does not re-debit. A reused key with a different payload returns IDEMPOTENCY_KEY_REUSED (422).

The debit defends in depth beyond the key. The OTP is consumed atomically with the debit, so a failed debit such as INSUFFICIENT_FUNDS leaves the OTP retryable. QR nonces are single-use. See Idempotency & Errors.

Planned: balance-check, void, and refund

Three operations are Planned (shape-frozen, not yet mounted). Wire them, but treat them as not-callable until they flip. Confirm at GET /capabilities.

• POST /v1/partner/redeem/balance-check is a non-debiting pre-flight that returns the two-class Balance plus an affordable boolean. It is advisory only: a TOCTOU window exists between it and the debit, so never use it as the sole insufficient-funds gate. The atomic gate is POST /payments itself.
• POST /v1/partner/redeem/void is a cashier void within a grace window. It reverses the debit and restores spent promo grants in FIFO-reverse order. Outside the window it returns VOID_WINDOW_EXPIRED.
• POST /v1/partner/refund/create is a merchant-initiated refund after the grace window. It records the refund as PENDING and settles the wallet credit asynchronously within 24 to 48 hours, then fires a refund.settled webhook.

Where to go next