Map account or Wallet address

Map a funding source to a user's wallet so that funds received through the assigned account or address can be credited directly to the wallet.

This endpoint supports mapping both fiat funding sources, such as static virtual accounts, and crypto funding sources, such as wallet addresses, to a user's wallet.

To complete the mapping, you provide the user's user_ref, the destination wallet_id, the funding source type, currency and chain, an account reference, and the user's KYC information.

The supported wallet currencies for this operation include NGN, EUSD, GBP, USD, EUR, USDT, and USDC.

Request

To map an account or address to a user's wallet, send a PUT request to the endpoint below.

PUT {{base_url}}/api/v1/user/subwallet-fund-source

Request Headers

Name	Type	Description
`Authorization`*	String	`Bearer ${api_key}` — your activated merchant API key.

Request Body

Name	Type	Description
`user_ref`	String	Unique reference identifying the user.
`wallet_id`	String	ID of the wallet to which the funding source will be mapped.
`fund_type`	String	Type of funding source, for example `STATIC_VIRTUAL_ACCOUNT`.
`chain`	String	Payment chain or funding source type, for example `FIAT_ACCOUNT`.
`currency`	String	Currency of the wallet and funding source, for example `NGN`.
`account_reference`	String	Unique reference for the account mapping from your system.
`user_kyc`	Object	KYC information of the user associated with the funding source.

`user_kyc` Fields

Name	Type	Description
`name`	String	Full name of the user.
`email`	String	Email address of the user.
`address`	String	Residential address of the user.
`phone`	String	Phone number of the user, including the country code.
`bvn`	String	Bank Verification Number of the user.
`dob`	String	Date of birth in `YYYY-MM-DD` format.

Sample Request

{
  "user_ref": "UREFB71CBD5EE9BE4AEFB0A1587839EAD87D007QQ",
  "wallet_id": "LBWNGN919E38DB1270460E8B094CB626AA3AAF00F6D",
  "fund_type": "STATIC_VIRTUAL_ACCOUNT",
  "chain": "FIAT_ACCOUNT",
  "currency": "NGN",
  "account_reference": "Tes-Test-001",
  "user_kyc": {
    "name": "Teslim Ayantola",
    "email": "[email protected]",
    "address": "No 6 sars road",
    "phone": "2348062551247",
    "bvn": "22300671783",
    "dob": "1987-05-03"
  }
}

Response

`200 OK`

{
  "status": "success",
  "message": "Assigned successfully",
  "fiat_data": {
    "funding_source_id": "e5640a6d-e94e-495e-94e2-79ce79bed978",
    "account_number": "7536780916",
    "bank_code": "Globus Bank",
    "currency": "NGN"
  },
  "crypto_data": {
    "funding_source_id": "",
    "address": "",
    "chain": ""
  }
}

Response Fields

Key	Type	Description
`status`	String	Indicates whether the funding source was successfully assigned.
`message`	String	Message describing the result of the request.
`fiat_data`	Object	Details of the assigned fiat funding source.
`crypto_data`	Object	Details of the assigned crypto funding source.

`fiat_data`

Returned when a fiat account is mapped to the wallet.

Key	Type	Description
`funding_source_id`	String	Unique ID of the assigned funding source.
`account_number`	String	Virtual account number assigned to the user.
`bank_code`	String	Bank associated with the virtual account.
`currency`	String	Currency of the virtual account.

`crypto_data`

Returned when a crypto address is mapped to the wallet.

Key	Type	Description
`funding_source_id`	String	Unique ID of the crypto funding source. Empty when not applicable.
`address`	String	Crypto wallet address assigned to the user. Empty when not applicable.
`chain`	String	Blockchain network associated with the address. Empty when not applicable.

How It Works

Once the funding source is successfully mapped, funds received through that account or address can be associated with the specified wallet.

For example, when an NGN static virtual account is assigned to an NGN wallet, deposits made to that virtual account can be credited to the user's wallet.

For crypto wallets, the corresponding blockchain address and chain identify where the user's crypto funds can be received.