Wallet Resolution (Username and Merchant name ) Internal

Resolves a user's internal wallet using their phone number and currency.

This endpoint works similarly to a traditional bank account-name enquiry. Instead of providing a bank account number, the merchant provides the user's phone number and currency. LedgerBlock resolves the matching wallet and returns the wallet owner's details, including the merchant name, username/tag, wallet ID, and account name.

This can be used to confirm the recipient's details before initiating an internal wallet transaction.

Endpoint

GET /api/v1/user/wallet/phone-lookup

Headers

Header	Description	Required
`x-merchant-ref`	Unique reference identifying the merchant	Yes

Query Parameters

Parameter	Description	Required
`phone`	Phone number associated with the user's wallet	Yes
`currency`	Currency of the wallet to resolve, for example `NGN`	Yes

Request

{{base_url}}/api/v1/user/wallet/phone-lookup?phone=08064642044&currency=NGN
--header 'x-merchant-ref: {{vault:x-merchant-ref}}'

Response

{
  "status": "success",
  "message": "Wallets resolved",
  "data": [
    {
      "merchant_name": "Fuspay Tech",
      "tag": "omanga",
      "wallet_id": "LBWNGN919E38DB1270460E8B094CB626AA3AAF00F6D",
      "account_name": "Charles Avis Ayodeji"
    }
  ]
}

Response Fields

Field	Description
`status`	Indicates whether the wallet resolution request was successful.
`message`	Describes the result of the wallet resolution.
`data`	Contains the wallet records resolved from the supplied phone number and currency.
`data[].merchant_name`	Name of the merchant associated with the wallet.
`data[].tag`	Username or unique tag associated with the wallet owner.
`data[].wallet_id`	Unique identifier of the resolved wallet.
`data[].account_name`	Name of the wallet owner.

How It Works

The merchant provides the user's phone number.
The merchant specifies the currency of the wallet they want to resolve.
LedgerBlock searches for matching internal wallets.
LedgerBlock returns the matching wallet details.
The merchant can use the returned account name, username/tag, merchant name, and wallet ID to confirm the recipient before proceeding with an internal transaction.

Example

A merchant wants to send NGN to a user and has the user's phone number:

Phone: 08064642044
Currency: NGN

LedgerBlock resolves the wallet and returns:

Merchant: Fuspay Tech
Username: omanga
Account Name: Charles Avis Ayodeji
Wallet ID: LBWNGN919E38DB1270460E8B094CB626AA3AAF00F6D

The merchant can then verify that the resolved recipient is the intended user before continuing with the transaction.

Use Cases

The Wallet Resolution endpoint can be used to:

Resolve an internal wallet using a phone number.
Confirm a recipient's account name before an internal transfer.
Retrieve the wallet ID required for subsequent wallet operations.
Identify the username/tag associated with a wallet.
Confirm the merchant associated with the wallet.
Provide an account-name-enquiry experience similar to traditional bank transfers.