Skip to main content
This guide explains how to add and activate non-custodial wallets so merchant settlements land at the correct address and network.

​
Use cases

  • Route settlement to a treasury wallet
  • Split environments (devnet vs mainnet) without changing code
  • Rotate settlement destinations for operational or compliance needs
  • Align settlement with embedded wallet infrastructure

​
How it works (client perspective)

  1. You add a non-custodial wallet address for the settlement network.
  2. You activate one wallet per network in the dashboard.
  3. Pepay sends all new settlements for that network to the active wallet.
  4. Settlements arrive in the merchant’s preferred settlement token (not the payor’s token).
Key implications:
  • The wallet must live on the settlement token’s chain.
  • The asset deposited is your settlement token (for example, USD1 on BSC).
  • Changing the active wallet changes where future settlements go.

​
Step 1 - Decide your settlement token

Choose the token you want to receive in (for example, USD1 on BSC). This token determines:
  • Which chain the wallet must support
  • Which asset will be deposited for every paid invoice

​
Step 2 - Add a non-custodial wallet

In the dashboard, add the wallet address for the settlement network. This registers it on the platform.

​
Step 3 - Activate the wallet

Newly added wallets must be activated in the dashboard. Activation sets the default settlement destination for that network. When activated:
  • All new payments settle to this wallet
  • Deposits arrive in the merchant’s preferred settlement token

​
Step 4 - Verify

Use the SDK to retrieve wallets and confirm which one is active: 
const wallets = await pepay.wallets.list();
console.log(wallets);

​
Wallet activation checklist

  • Settlement token configured in the dashboard
  • Wallet address added for the settlement network
  • Wallet activated (one active per network)
  • Test invoice paid and settlement received
  • Active wallet recorded in your internal ops runbook

​
Operational notes

  • Use one active wallet per network.
  • Store wallet metadata in your system for reconciliation.
  • If you change the active wallet, update downstream accounting rules.
If you want help configuring wallet management, reach out at [email protected].