Skip to main content
Every organization must configure a settlement wallet: the Stellar public key that receives payments.

​
Setup

Settlement wallets are configured during onboarding and can be updated in Settings → Settlement Wallet. Requirements:
  • Valid Stellar public key (G... address)
  • Connected via Stellar Wallet Kit for proof of ownership
  • Separate wallet per environment (sandbox and production)

​
Accepted assets

By default, organizations accept:
  • XLM: native Stellar lumens
  • USDC: Circle USDC on Stellar
The settlement wallet must be able to receive the asset being paid:
AssetRequirement
XLMAccount must exist and be funded (minimum balance)
USDCAccount must have a trustline to the network USDC issuer

​
USDC trustlines

USDC on Stellar is issued by Circle. Your settlement wallet needs an active trustline to the correct issuer:
NetworkEnvironment variable
TestnetSTELLAR_TESTNET_USDC_ISSUER
MainnetSTELLAR_MAINNET_USDC_ISSUER
Circle testnet issuer example: 
GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
If the merchant or customer wallet lacks a USDC trustline, checkout returns a clear error before the transaction is submitted.

​
How it affects payments

When you create a payment, Payoes snapshots the settlement address into the payment record. The checkout transaction always sends funds to that address. Changing the settlement wallet after creating a payment does not affect existing pending payments.

​
Security notes

  • Payoes never holds private keys for merchant wallets
  • Wallet connection during setup proves you control the address
  • Use a dedicated settlement wallet rather than a personal hot wallet for production