Request Wallet Debit

Requests a debit from a source wallet and initiates the transfer of the requested funds to a target wallet.

Unlike an immediate wallet-to-wallet transfer, this operation requires authorization from the source wallet using the wallet PIN and OTP. After the debit request is authorized, settlement of the target wallet occurs within the applicable T + x settlement period.

Endpoint

POST /api/v1/user/wallet/debit

Authorization

Bearer Token

A valid Bearer Token is required to authenticate the request.

Headers

Header	Description	Required
`Authorization`	Bearer token used to authenticate the request	Yes
`Content-Type`	Specifies that the request body is JSON	Yes
`x-merchant-ref`	Unique reference identifying the merchant	Yes

Request Body

Field	Description	Required
`user_ref`	Reference of the user initiating the debit request	Yes
`source_wallet_id`	ID of the wallet from which the funds will be debited	Yes
`target_wallet_id`	ID of the wallet that will receive the funds after settlement	Yes
`txn_ref`	Unique transaction reference generated by the merchant	Yes
`amount`	Amount requested to be debited	Yes
`currency`	Currency of the debit request	Yes
`notification_url`	URL where LedgerBlock sends transaction status notifications	Yes

Request

curl --location -g '{{base_url}}/api/v1/user/wallet/debit' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-merchant-ref: {{vault:x-merchant-ref}}' \
--data '{
    "user_ref": "{{vault:Merchant-user-ref}}",
    "source_wallet_id": "{{vault:source-wallet-id}}",
    "target_wallet_id": "{{vault:target-wallet-id}}",
    "txn_ref": "lgb_live_009",
    "amount": 10,
    "currency": "NGN",
    "notification_url": "{{notification_url}}"
}'

Authorization Requirements

A wallet debit request requires authorization from the source wallet.

The source wallet's:

Wallet PIN
OTP

are required before the debit can be authorized and processed.

This provides an additional authorization layer to ensure that the wallet owner has approved the debit.

Settlement

The target wallet is not necessarily settled immediately after the debit request is initiated.

Settlement occurs within the applicable T + x timeframe, where x represents the number of additional settlement days defined for the transaction.

The transaction should therefore be treated as asynchronous, with the final transaction status communicated through the configured notification_url.

Debit Flow

Merchant
   │
   │ Request Debit
   ▼
Source Wallet
   │
   │ Wallet PIN + OTP
   ▼
Authorization
   │
   │ Debit Request Processed
   ▼
Settlement
   │
   │ T + x
   ▼
Target Wallet

Wallet Roles

Source Wallet

The wallet from which the requested amount is debited. Authorization using the wallet PIN and OTP is required.

Target Wallet

The wallet that receives the funds after the settlement process is completed.

Transaction Reference

The txn_ref should uniquely identify the debit transaction.

For example:

lgb_live_009

Merchants should retain this reference for transaction tracking and reconciliation.

Notifications

The notification_url allows LedgerBlock to notify the merchant about changes to the transaction status.

Because settlement occurs asynchronously, merchants should use the notification mechanism to determine the final outcome rather than assuming that the initial debit request means the target wallet has already been settled.

Use Cases

The Request Wallet Debit endpoint can be used to:

Request funds from a user's source wallet.
Initiate an authorized debit using the wallet PIN and OTP.
Transfer funds to a target wallet through a settlement process.
Track an asynchronous debit transaction.
Receive transaction status updates through a notification URL.