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.