Wallet Lookup

Who calls these endpoints?External API (s2s)

Base path: /api/v1/wallet
Identity: Ed25519 request signature — X-Key-Id, X-Date, X-Nonce, Digest (when there is a body), X-Signature. ±5 min clock window, single-use nonce, optional per-key IP allow-list.
Authorization: The key must carry the wallet product and the wallet permission the call requires; a call without it gets 403 WALLET_INSUFFICIENT_SCOPE. Permissions per endpoint: Key permissions.
Cross-surface: This endpoint exists on the s2s surface only. Although it looks like a read, it requires wallet:enduser:manage or wallet:program:manage on your key; read permissions do not open it.

POST /api/v1/wallet/wallets/lookup

Tells you whether a phone number or wallet number leads to a wallet that can transact. The response is deliberately narrow: exists or not, the wallet number and a masked name. The user's id, balance or clear phone is not returned.

Typical use: before a wallet-to-wallet transfer, show the sender the recipient's masked name so they can confirm they are sending to the right person.

Request

No Idempotency-Key is needed.

Body field	Type	Required	Rule
`phone`	string	⚠️	The recipient's phone; same rules as on create. Send it with the country code.
`programId`	string (UUID)	✅ with `phone`	Required for a phone lookup, because the phone is unique within a program.
`walletNo`	string	⚠️	10-digit wallet number (`^\d{10}$`).

⚠️ Either phone or walletNo is required. If both are sent, the phone is used.

curl -X POST "https://api-gateway.lunixi.com/api/v1/wallet/wallets/lookup" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: …" -H "X-Date: …" -H "X-Nonce: …" -H "Digest: …" -H "X-Signature: …" \
  -d '{"programId":"5b9e2f3a-7c41-4d8e-a6f2-9e1b3c4d5f60","phone":"+905339876543"}'

Response

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "exists": true,
    "walletNo": "4826190375",
    "maskedName": "M***** Ö****"
  },
  "requestId": "…"
}

Field	Type	Meaning
`exists`	boolean	Whether a wallet that can transact was found.
`walletNo`	string \| null	For a phone lookup, the number of the user's default wallet; for a wallet-number lookup, that wallet's number. `null` when `exists: false`.
`maskedName`	string \| null	The user's masked display name; the masked phone if there is no name. `null` when `exists: false`.

When nothing is found, the response is still successful:

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": { "exists": false, "walletNo": null, "maskedName": null },
  "requestId": "…"
}

When `exists: false` is returned

The phone is not registered in the program, or the wallet number does not belong to one of your wallets.
The user is not ACTIVE (FROZEN or CLOSED).
For a wallet-number lookup, the wallet is not ACTIVE.

Other merchants' users and wallets are never found; the response does not reveal whether a number exists in another account.

A phone lookup searches only the program you give in programId. A wallet-number lookup searches all your programs; in a wallet-to-wallet transfer, however, the recipient must be in the same program as the sender. Always validate the transfer with a quote first.

Privacy

The response contains no clear phone, clear name or user id; the name is returned masked only (M***** Ö****). Show the masked name to the sender so they can confirm the recipient.

Errors

HTTP	Code	When
400	`VALIDATION_ERROR`	A field has the wrong format (`walletNo` is not 10 digits, `programId` is not a UUID, the phone contains disallowed characters) or the body contains an undefined field
400	`WALLET_VALIDATION`	Neither `phone` nor `walletNo` was sent; `phone` without `programId`; the phone does not have 8–15 digits after normalization
403	`WALLET_INSUFFICIENT_SCOPE`	The key lacks `wallet:enduser:manage` or `wallet:program:manage`

Wallets & Accounts Top-up