Dynamic Virtual accounts

Creates a dynamic subwallet collection and generates a virtual bank account for the customer to make payment.

If the payment is successful, LedgerBlock sends a notification to the configured notification_url.

Method: POST

Endpoint:

{{base_url}}/api/v1/collection/subwallet

Authentication

Bearer Token

Include the Bearer token in the Authorization header.

Headers

Header	Value
Authorization	`Bearer <token>`
x-merchant-ref	`<merchant-ref>`
Content-Type	`application/json`

Request Body

{
  "user_ref": "USER-REF-001",
  "txn_merchant_ref": "TXN-REF-001",
  "amount": 100,
  "currency": "NGN",
  "chain": "",
  "payment_method": "DYNAMIC_VIRTUAL_ACCOUNT",
  "pay_meta_data": {},
  "notification_url": "https://example.com/webhook"
}

Request Fields

Field	Required	Description
`user_ref`	Yes	Reference of the user making the payment
`txn_merchant_ref`	Yes	Unique merchant reference for the transaction
`amount`	Yes	Amount to be collected
`currency`	Yes	Currency of the collection
`chain`	No	Blockchain/network. Leave empty for NGN virtual account collection
`payment_method`	Yes	Payment method. Use `DYNAMIC_VIRTUAL_ACCOUNT`
`pay_meta_data`	No	Additional payment metadata
`notification_url`	Yes	URL where LedgerBlock sends payment status notifications

Response

{
  "status": "success",
  "message": "Please complete payment",
  "data": {
    "payment_ref": "PAYMENT-REF-001",
    "txn_merchant_ref": "TXN-REF-001",
    "amount": 100,
    "currency": "NGN",
    "pay_data": {
      "account_name": "Test Merchant",
      "account_number": "0123456789",
      "bank_code": "000001",
      "bank_name": "Test Bank",
      "expires": ""
    }
  }
}

Response Fields

Field	Description
`status`	Status of the request
`message`	Message indicating that payment should be completed
`data.payment_ref`	LedgerBlock payment reference
`data.txn_merchant_ref`	Merchant reference for the transaction
`data.amount`	Amount to be paid
`data.currency`	Currency of the collection
`data.pay_data.account_name`	Name associated with the virtual account
`data.pay_data.account_number`	Dynamic virtual account number generated for the payment
`data.pay_data.bank_code`	Bank code of the virtual account
`data.pay_data.bank_name`	Bank name of the virtual account
`data.pay_data.expires`	Expiration time of the virtual account, if applicable

Collection Flow

Create Dynamic Virtual Account → Customer Makes Payment → Payment Successful → Notification Sent to notification_url

The generated virtual account details in pay_data should be provided to the customer to complete the payment. Once payment is successfully received, LedgerBlock sends the transaction notification to the configured notification_url.