Create an End User

POST /api/v1/wallet/end-users

Creates the end user and, in the same operation, opens their default wallet with a single account. The response returns the user together with this wallet and its account.

Headers

Body fields

The body may contain only the fields below; any other field is rejected with 400 VALIDATION_ERROR.

How the phone is stored

The phone number is not stored in plain text. A one-way digest (for lookups and uniqueness) and a masked form are derived from the normalized digits. The masked form keeps the first 4 and last 2 digits visible: +905321234567 → 9053******67. Responses return the phone only as phoneMasked.

How the display name is stored

displayName is masked so that the first letter of each word stays visible and the rest becomes * (at most 8 stars per word, at most 64 characters in total): Ayşe Yılmaz → A*** Y*****. The clear form is not stored and cannot be read back. The masked name is shown in wallet lookup to confirm the recipient; without it, the masked phone is shown there.

Opening currency

The default wallet opens with a single account. Its currency is determined in this order:

1. If corporateAccountId is given, the corporate account's funding currency. If you also send defaultCurrency, it must equal the funding currency; otherwise the request is rejected with 400 WALLET_VALIDATION.
2. If defaultCurrency is given, that currency.
3. Otherwise, your program's main currency.

If your program has no main currency set and you did not send defaultCurrency, the request is rejected with 409 WALLET_PROGRAM_CURRENCY_UNDESIGNATED and nothing is created. No guess is made from the program's currency list. Open accounts in other currencies afterwards: Wallets & Accounts.

Idempotency

Idempotency-Key is required and binds the request so it is processed once:

• Repeating the same request with the same key returns the first successful response as is; no second user is created.
• Using the same key with a different request returns 409 WALLET_IDEMPOTENCY_CONFLICT. The comparison covers programId, accountType, phone, externalCustomerId, corporateAccountId and defaultCurrency.
• If the first request failed, the key is released; you can retry with the same key.

All scenarios and the recommended integration pattern: Creating Twice.

Example

curl -X POST "https://api-gateway.lunixi.com/api/v1/wallet/end-users" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: enduser-crm-88213" \
  -H "X-Key-Id: …" -H "X-Date: …" -H "X-Nonce: …" -H "Digest: …" -H "X-Signature: …" \
  -d '{"programId":"5b9e2f3a-7c41-4d8e-a6f2-9e1b3c4d5f60","accountType":"PERSONAL","phone":"+905321234567","externalCustomerId":"crm-88213","displayName":"Ayşe Yılmaz","defaultCurrency":"TRY"}'

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "endUser": {
      "id": "8d4c2a1f-3b6e-4f7a-9c5d-2e8b1a0f6c34",
      "programId": "5b9e2f3a-7c41-4d8e-a6f2-9e1b3c4d5f60",
      "accountType": "PERSONAL",
      "externalCustomerId": "crm-88213",
      "corporateAccountId": null,
      "corporateOffboardedAt": null,
      "kycRef": null,
      "kycLevelCache": null,
      "kycLevelRefreshedAt": null,
      "phoneMasked": "9053******67",
      "displayNameMasked": "A*** Y*****",
      "merchantCategory": null,
      "status": "ACTIVE",
      "createdAt": "2026-10-11T09:15:02.418Z",
      "updatedAt": "2026-10-11T09:15:02.418Z"
    },
    "defaultWallet": {
      "id": "1e7f9a3b-5c2d-4a8e-b6f1-3d9c0e2a7b58",
      "endUserId": "8d4c2a1f-3b6e-4f7a-9c5d-2e8b1a0f6c34",
      "walletNo": "5810763412",
      "name": "Cüzdanım",
      "isDefault": true,
      "status": "ACTIVE",
      "accounts": [
        {
          "id": "c2a5e8f1-9d3b-4c7a-8e6f-5b1d2a9c0e47",
          "walletId": "1e7f9a3b-5c2d-4a8e-b6f1-3d9c0e2a7b58",
          "currency": "TRY",
          "accountCode": 5000,
          "fullWalletNo": "58107634125000",
          "status": "ACTIVE"
        }
      ],
      "createdAt": "2026-10-11T09:15:02.418Z"
    }
  },
  "requestId": "…"
}

The meaning of the endUser fields is on Detail & Lookup. In money movements you use defaultWallet.accounts[].id (the walletAccountId) as the source account. The default wallet is always named Cüzdanım.

Errors