POST
/
api
/
v1
/
wallets
curl --location 'https://api.recital.finance/api/v1/wallets' \
--header 'Authorization: Bearer apiKey' \
--header 'Content-Type: application/json' \
--data-raw '{
  "alias": "test wallet",
  "providerID": "0001",
  "currencies": ["NGN", "USD", "SLL"],
  "operations": ["COLLECTION"],
  "connectID": "HnwiseDy8HB2GOV"
}'

{
  "message": "Wallet successfully created",
  "success": true,
  "walletId": "RC_WAL-NEWLYCREATEDID"
}
​
alias
string
A human-readable name to help identify this wallet.
​
providerID
string
Identifier of the provider powering this wallet (e.g., “0001” for Monnify, etc.).
​
linkWalletID
string
This is optional. The walletId you want to link to this for the first time.
​
groupWalletID
string
This is optional. The parent wallet this provider wallet is grouped under, this is returned after the first linking.
​
currencies
array of strings
List of supported currencies for this wallet (provider enabled currencies).
​
operations
array of strings
List of supported operations. Possible values: COLLECTION, DISBURSEMENT, etc.
​
connectID
string
The connect ID allowed to interact with this wallet. This can be gotten from the response on listing your providers.
curl --location 'https://api.recital.finance/api/v1/wallets' \
--header 'Authorization: Bearer apiKey' \
--header 'Content-Type: application/json' \
--data-raw '{
  "alias": "test wallet",
  "providerID": "0001",
  "currencies": ["NGN", "USD", "SLL"],
  "operations": ["COLLECTION"],
  "connectID": "HnwiseDy8HB2GOV"
}'

​
Response

​
message
string
Describes the result of the wallet creation.
​
success
boolean
Indicates whether the wallet creation request was successful.
​
walletId
string
The unique identifier of the newly created wallet.
{
  "message": "Wallet successfully created",
  "success": true,
  "walletId": "RC_WAL-NEWLYCREATEDID"
}

​
Status Codes

CodeDescription
201Wallet created successfully
400Validation error or duplicate wallet
401Unauthorized access or invalid API key
500Server error while creating the wallet

​
Notes

  • A groupWalletID must already exist and be valid.
  • Each connectId will be authorized to transact on the new wallet.
  • Ensure the provider supports the given currencies and operations.

​
Best Practices

✅ Use descriptive aliases to organize wallets efficiently.
✅ Group related wallets under a single groupWalletID for better structure.
✅ Confirm provider capabilities (currency/operation support) before provisioning.