🔗 Linking Wallets to Enable Multi-Provider Support - Recital Documentation

Recital lets you link multiple wallets — each backed by a different payment provider — into one group using a shared groupWalletID. This allows you to:

Associate a wallet with multiple providers
Fund wallets by currency — Recital routes to the provided provider
Centralize wallet activity while maintaining separation per provider

⚠️ Rules 1 wallet = 1 provider Group must have unique providers only connectId must match the selected provider groupWalletId must be consistent across linked wallets

🛠 How Wallet Linking Works

To enable multi-provider support, wallets must be linked under a common groupWalletID. Here’s how the process works:

First Wallet Linking

When creating a new wallet, include the linkWalletID — the walletId of an existing wallet you want to link to. This will return a groupWalletID, which will be used to group all related wallets. ⚠️ If valid, the group is created or updated, and all linked wallets will share the same groupWalletID.

Subsequent Wallets in the Group

For all future wallets you want to add to the same group, simply provide the same groupWalletID — no need to include linkWalletID again. This lets you build a virtual wallet group across providers, and allows smart routing by provider and/or currency.

Sample Linking Request

{
  "alias": "test wallet",
  "providerID": "0002",
  "linkWalletID": "RC_WAL-**********",
  "currencies": ["NGN", "USD", "SLL"],
  "operations": ["COLLECTION"],
  "connectID": "****************"
}

Sample Grouping Request

{
  "alias": "test wallet2",
  "providerID": "0001",
  "groupWalletID": "RC_WAL-**********",
  "currencies": ["NGN", "USD", "SLL"],
  "operations": ["PAYOUT"],
  "connectID": "****************"
}