Wallet as a Service

LedgerBlock Wallet as a Service allows merchants to create and manage wallets for their users and perform wallet-related financial operations through the LedgerBlock API.

A wallet can be associated with a LedgerBlock User and used as part of the user's financial activity.

The Wallet as a Service flow covers:

• Creating wallets
• Mapping and managing funding sources
• Resolving wallets using a phone number
• Requesting wallet debits
• Transferring funds between wallets

Creating Wallets

A wallet is a financial account associated with a LedgerBlock User.

Before creating a wallet, the User must exist on LedgerBlock and satisfy any applicable requirements for the wallet being created.

Wallet Creation Flow

Create User
     ↓
Complete Required KYC
     ↓
Create Wallet
     ↓
Wallet Created
     ↓
Wallet Available for Transactions

Your application should retain the wallet reference returned by LedgerBlock. This reference can be used when performing subsequent wallet operations.

Create a Wallet

Use the Create Wallet API to create a wallet for an existing User.

For the required parameters, headers, and response structure, see:

Create Wallet API → Create Wallet

Note: Wallet availability and capabilities may depend on the User's KYC status and the requirements of the wallet service.

Mapping and Managing Funding Sources

A funding source represents an external account or financial source that can be associated with a wallet for funding or other supported financial operations.

LedgerBlock allows supported funding sources to be mapped to a User or wallet.

The mapping process allows your application to establish the relationship between the wallet and its supported funding source.

Funding Source Flow

Funding Source
      ↓
Map Funding Source
      ↓
Wallet
      ↓
Manage / Use Funding Source

Managing Funding Sources

Depending on the supported operation, your application can manage the funding sources associated with a wallet.

Typical management operations may include:

• Adding a funding source
• Mapping a funding source
• Retrieving mapped funding sources
• Updating funding-source information
• Removing or unlinking a funding source

For the available operations and required request parameters, see the relevant Funding Source API documentation.

Funding Source APIs → Get Funding Sources (Account or address mapped to a wallet)

Only supported funding-source types can be mapped to a LedgerBlock wallet.

Wallet Resolution — Phone Based

Wallet resolution allows your application to determine the wallet associated with a user's phone number.

This can be useful when initiating a wallet-based transaction where the sender or recipient is identified by a phone number rather than directly by a wallet reference.

Resolution Flow

Phone Number
     ↓
Wallet Resolution
     ↓
Wallet / User Identified
     ↓
Proceed With Supported Operation

Your application provides the phone number to the wallet-resolution endpoint.

LedgerBlock then resolves the phone number against the supported wallet records and returns the applicable wallet information.

Example Use Case

A customer wants to send money to another LedgerBlock User but only knows the recipient's phone number.

Your application can:

1. Receive the recipient's phone number.
2. Resolve the phone number.
3. Retrieve the corresponding wallet information.
4. Display the recipient details for confirmation.
5. Initiate the supported wallet operation.

For the request and response structure, see:

Wallet Resolution API → [Link to Wallet Resolution API]

Important: Always confirm the resolved recipient information before initiating a transaction.

Request Debit

A debit request allows your application to request funds to be debited from a supported wallet.

Debit operations should only be initiated when the required wallet, User, and authorization conditions have been satisfied.

Debit Flow

Debit Request
      ↓
Validate Wallet
      ↓
Validate Available Balance / Requirements
      ↓
Process Debit
      ↓
Transaction Result

Your application should use the Request Debit API to initiate a debit operation.

For the required request parameters, authentication headers, response structure, and transaction statuses, see:

Request Debit API → [Link to Request Debit API]

Handling Debit Results

After submitting a debit request, do not assume that the transaction was successful solely because the API request was accepted.

Use the transaction response and, where applicable, the relevant webhook notification to determine the final transaction status.

Wallet Transfers

Wallet transfers allow funds to be moved between supported wallets.

A transfer generally identifies the source wallet and destination wallet together with the amount and other required transaction information.

Transfer Flow

Source Wallet
      ↓
Transfer Request
      ↓
Validate Transaction
      ↓
Debit Source Wallet
      ↓
Credit Destination Wallet
      ↓
Transaction Status

Initiating a Transfer

Use the Wallet Transfer API to initiate a transfer between supported wallets.

Your application should provide the required transaction information specified by the API.

For the complete request and response structure, see:

Wallet Transfer API → Wallet to wallet Transfer (Same Currencies)

Transfer Status

A wallet transfer may pass through different transaction states during processing.

Your application should use the returned transaction information and applicable webhook notifications to determine whether the transfer was:

• Successful
• Pending
• Failed

Do not mark a transfer as successful in your application until LedgerBlock has returned or notified your application of a successful transaction status.

Recommended Wallet Integration Flow

A typical Wallet as a Service integration can follow this sequence:

1. Create User
       ↓
2. Complete Required KYC
       ↓
3. Create Wallet
       ↓
4. Map Funding Source
       ↓
5. Manage Wallet / Funding Source
       ↓
6. Resolve Wallet When Required
       ↓
7. Request Debit or Transfer
       ↓
8. Monitor Transaction Status
       ↓
9. Process Webhook Notification

API References

Use the following API references to implement Wallet as a Service:

Important: The Guides section explains the purpose and recommended flow of each wallet capability. For exact request parameters, authentication requirements, response fields, and endpoint examples, refer to the corresponding API Reference.