Wallet-to-Wallet Transfer

Transfers funds from one internal LedgerBlock wallet to another wallet.

The transfer requires a source wallet, target wallet, transaction reference, amount, and currency. The user_ref identifies the user initiating the transfer.

Endpoint

POST /api/v1/user/wallet/transfer

Authorization

Bearer Token

The request must include a valid Bearer Token.

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 transfer	Yes
`source_wallet_id`	ID of the wallet funds will be deducted from	Yes
`target_wallet_id`	ID of the wallet that will receive the funds	Yes
`txn_ref`	Unique transaction reference generated by the merchant	Yes
`amount`	Amount to transfer	Yes
`currency`	Currency of the transfer, for example `NGN`	Yes
`notification_url`	URL that LedgerBlock can use to send transaction status notifications	Yes

Request

curl --location -g '{{base_url}}/api/v1/user/wallet/transfer' \
--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_008",
    "amount": 10,
    "currency": "NGN",
    "notification_url": "{{notification_url}}"
}'

How It Works

The merchant identifies the user initiating the transfer using user_ref.
The source_wallet_id identifies the wallet from which the funds will be deducted.
The target_wallet_id identifies the receiving internal wallet.
LedgerBlock processes the transfer for the specified amount and currency.
The merchant's txn_ref is used to uniquely identify the transaction.
LedgerBlock sends transaction notifications to the configured notification_url.

Transfer Flow

Source Wallet
     │
     │  Amount + Currency
     ▼
LedgerBlock
     │
     │  Internal Wallet Transfer
     ▼
Target Wallet

Use Cases

The Wallet-to-Wallet Transfer endpoint can be used to:

Transfer funds between internal LedgerBlock wallets.
Move funds between users within the same supported currency.
Initiate user-to-user transfers using wallet IDs.
Track transfers using a merchant-generated transaction reference.
Receive transaction status updates through a notification URL.