WalletMultiple NGN Wallets

Multiple NGN Wallets

SaySwitch supports multiple NGN wallets for merchants who have been enabled for this feature. The default NGN wallet continues to work exactly as before. Merchants can create additional custom NGN wallets, receive payments into a specific wallet, initiate payouts from a selected wallet, and move funds between SaySwitch wallets.

How It Works

  • Multiple NGN wallet support is only available for NGN.
  • Merchants must be enabled for multiple NGN wallets before using custom wallet APIs.
  • The default wallet remains the merchant’s main wallet.
  • Existing default-wallet APIs continue to use the default wallet.
  • Normal/default S2S endpoints do not accept wallet_code. The dedicated virtual-account endpoint is an exception and has the conditional behavior explained below.
  • Wallet-specific S2S endpoints require wallet_code.

Dedicated Virtual Accounts

Dedicated accounts continue to use the existing endpoint:

POST /api/v1/dedicated_virtual_account

Do not use a new /wallet endpoint for dedicated accounts.

  • When multiple NGN wallets are disabled, omit wallet_code. The endpoint selects the active default NGN wallet, falling back to the oldest active NGN wallet when no default is marked. Supplying a code does not override this selection.
  • When multiple NGN wallets are enabled, wallet_code is required whether you supply an existing customer code or create the customer inline.
  • The wallet must be active, use NGN, belong to the authenticated merchant, and match the test/live environment.
  • This endpoint accepts wallet_code, not wallet_id.

See Create Dedicated Virtual Account for both customer formats and complete single-wallet and multiple-wallet examples.

Wallet Types

TypeDescription
Default walletAutomatically created during onboarding or activation. Existing integrations use this wallet.
Custom walletManually created by the merchant. It has its own wallet_code and dedicated virtual account where applicable.
wallet_codeUnique wallet identifier used for wallet-specific API operations.

Create NGN Wallet

Create a custom NGN wallet for a merchant enabled for multiple NGN wallets.

Endpoint

POST /api/s2s/v1/wallet/create-ngn

Headers

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Request Body

curl --request POST \
  --url https://backendapi.sayswitchgroup.com/api/s2s/v1/wallet/create-ngn \
  --header "Authorization: Bearer YOUR_LIVE_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Operations Wallet"
  }'

Sample Response

{
  "success": true,
  "message": "Wallet created successfully",
  "data": {
    "wallet": {
      "id": 123,
      "title": "Operations Wallet",
      "wallet_code": "NGN169XXXX",
      "currency": "NGN",
      "is_default": 0,
      "is_custom": 1,
      "domain": "live",
      "status": 1
    },
    "virtual_account": {
      "account_number": "1234567890",
      "bank_name": "Wema Bank"
    }
  }
}

Notes

  • Custom NGN wallet creation is only available to merchants enabled for multiple NGN wallets.
  • Custom wallet creation should be used in live mode.
  • Store the returned wallet_code for wallet-specific payments, payouts, and wallet transfers.

Wallet-To-Wallet Transfer

Move funds from one SaySwitch NGN wallet to another.

Endpoint

POST /api/s2s/v1/wallet/transfer

Request Body

curl --request POST \
  --url https://backendapi.sayswitchgroup.com/api/s2s/v1/wallet/transfer \
  --header "Authorization: Bearer YOUR_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "source_wallet_code": "NGN169SOURCE",
    "destination_wallet_code": "NGN200DEST",
    "amount": 5000,
    "reference": "WTW_1234567890123456",
    "narration": "Move funds"
  }'

Sample Response

{
  "success": true,
  "message": "Wallet transfer successful",
  "data": {
    "reference": "WTW_1234567890123456",
    "amount": 5000,
    "fee": 0,
    "currency": "NGN",
    "status": "success",
    "wallet_id": 123,
    "wallet_code": "NGN169SOURCE",
    "account_number": "NGN200DEST",
    "bank_name": "SaySwitch Wallet"
  }
}

Rules

  • source_wallet_code must belong to the authenticated merchant.
  • destination_wallet_code can belong to any merchant on SaySwitch.
  • Source and destination wallets must both be NGN.
  • Source and destination wallets must be on the same domain.
  • Test wallets cannot transfer to live wallets, and live wallets cannot transfer to test wallets.
  • Source wallet must have sufficient balance.
  • Wallet-to-wallet transfer fee is 0.
  • A webhook is sent using the existing payout/transfer webhook flow.

Wallet-Specific S2S Collections

ActionEndpoint
Create NGN walletPOST /api/s2s/v1/wallet/create-ngn
Initialize S2S card payment with walletPOST /api/s2s/v1/transaction/initialize/wallet
Initialize S2S OPay payment with walletPOST /api/s2s/v1/transaction/opay/initialize/wallet
Initialize S2S bank transfer with walletPOST /api/s2s/v1/banktransfer/initialize/wallet
Initialize S2S USSD payment with walletPOST /api/s2s/v1/ussd/initialize/wallet
Wallet-to-wallet transferPOST /api/s2s/v1/wallet/transfer
Initiate payout from walletPOST /api/v1/bank_transfer/wallet
Get specific wallet balanceGET /api/v1/wallet_balance/NGN/{wallet_code}

Only NGN multiple-wallet balance is supported for now.

Common Errors

Wallet Not Found

{
  "success": false,
  "message": "Wallet not found"
}

Multiple Wallet Not Enabled

{
  "status": false,
  "message": "Multiple NGN wallets is not enabled for this business"
}

Missing wallet_code

{
  "status": false,
  "message": "wallet_code is required for this endpoint"
}

wallet_code Sent To Default Endpoint

{
  "status": false,
  "message": "wallet_code is only allowed on the wallet-specific endpoint"
}

Insufficient Wallet Balance

{
  "success": false,
  "message": "Insufficient wallet balance"
}