Top-up

Money enters the wallet three ways: by card, as cash through an agent, and by bank transfer. All three share the same operation model — each top-up produces an operation record and the outcome is delivered by webhook. Starting a card or agent top-up requires an Idempotency-Key.

Card top-up

Card top-ups are delegated to the payment stack; card data never touches your server. Routing, 3D Secure and provider selection happen on the payment side, and the result lands in the wallet.

Start the top-up

POST /api/v1/wallet/topups/card

curl -X POST "https://api-gateway.lunixi.com/api/v1/wallet/topups/card" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: topup-crm-88213-1" \
  -H "X-Key-Id: …" -H "X-Signature: …" \
  -d '{
    "creditWalletAccountId": "c2a5e8f1-9d3b-4c7a-8e6f-5b1d2a9c0e47",
    "amount": "25000",
    "currency": "TRY",
    "returnUrl": "https://app.acme.com/wallet/topup/result"
  }'

{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "operationId": "4f1b8d2e-6a9c-4b3e-8f7d-1c5e9a2b6d08",
    "paymentId": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "status": "INITIALIZED",
    "checkoutFormContent": "<script …>",
    "threeDsHtml": "",
    "redirectUrl": ""
  }
}

The response offers three possible continuations — use whichever is populated:

Get the outcome

GET /api/v1/wallet/topups/{operationId}

Status flow:

Related webhooks

Top-up refund

A completed card top-up can be refunded — money returns to the card and leaves the wallet balance.

POST /api/v1/wallet/topups/{operationId}/refund

A refund runs in this order:

1. The top-up moves to REVERSING. A concurrent second refund or reversal of the same top-up cannot win this step and moves no money.
2. The amount is debited from the wallet balance.
3. The amount is refunded to the card.
4. The top-up becomes REVERSED and the wallet.topup.refunded webhook is sent.

If the outcome of step 2 or 3 cannot be settled at that moment (timeout, provider unreachable), the top-up stays in REVERSING. The system completes the refund automatically with the same keys; the amount never moves a second time from the wallet or to the card. You do not need to restart the refund; repeating the same request resumes it.

Agent top-up

If you run an agent/dealer network, the agent takes cash and credits the customer's wallet from their own float account. Money moves inside the tenant; nothing enters from outside.

POST /api/v1/wallet/agent-topups

curl -X POST "https://api-gateway.lunixi.com/api/v1/wallet/agent-topups" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: agent-4471-20260807-0012" \
  -H "X-Key-Id: …" -H "X-Signature: …" \
  -d '{
    "agentId": "6b2e9f4a-3c8d-4e1b-9a7f-5d0c3e8b2a61",
    "creditWalletAccountId": "c2a5e8f1-9d3b-4c7a-8e6f-5b1d2a9c0e47",
    "amount": "50000",
    "currency": "TRY"
  }'

The response status is normally COMPLETED. If the ledger outcome cannot be settled at that moment it is INDETERMINATE: the credit may have been made and the system settles the operation on its own. Do not tell the agent "the top-up failed" and do not retry with a new Idempotency-Key; repeating with the same key returns the operation's current state. See Uncertain outcome.

Agents and float management are configured in the merchant panel: Panel — Programs.

Bank transfer top-up

Bank transfer top-up works by giving each user a dedicated deposit reference. The user sends money quoting it, and inbound funds are matched to that reference and credited to the wallet.

Create a deposit instruction

POST /api/v1/wallet/end-users/{endUserId}/deposit-instructions

List instructions

GET /api/v1/wallet/end-users/{endUserId}/deposit-instructions

Always read the IBAN and reference you display from this endpoint; never hard-code them.

Once matched, wallet.topup.completed fires with fundingSourceType indicating the bank-transfer source.

Common mistakes