Merchant External Accounts
Merchant External Accounts
Configure your merchant’s external bank accounts and crypto wallets to receive funds from virtual account settlements and crypto purchases.
What are Merchant External Accounts?
Merchant External Accounts are your merchant’s own bank accounts and crypto wallets where you receive funds from Koywe operations.
Types of External Accounts
Your company bank accounts for receiving fiat settlements and withdrawals
Your crypto wallet addresses for receiving cryptocurrency from ONRAMP deals
External Bank Accounts vs Virtual Accounts
Understanding the difference:
Automatic Settlement: Funds in virtual accounts are automatically settled to your registered external bank account after a configured period (typically 1-7 days). You can also manually request withdrawals.
Setting Up External Bank Accounts
When You Need an External Bank Account
✅ Required for:
- Receiving automatic settlements from virtual accounts
- Withdrawing funds from virtual balances
- Receiving merchant payouts
- Compliance and verification
Creating an External Bank Account
Automatic Association: Bank accounts are automatically associated with your merchant’s registered business information. No need to send holder name or document numbers - we use the information already in the system.
Required Fields by Country
Bank Code Flexibility: For most countries, the bank code can be deduced from the account number. You can still provide it, but the API will validate against the deduced value. For countries where it’s required, validation ensures the bank is in the supported list.
Chile 🇨🇱
Validations: Bank code must be in the valid banks list.
Colombia 🇨🇴
Validations: Account type must be supported by the bank. Account number length validated (min/max).
Brazil 🇧🇷
Validations: Bank code deduced from account number. PIX key can be used instead of account number.
Mexico 🇲🇽
Validations: CLABE format validation (18 digits). Check digit validation. Bank deduced from CLABE.
Argentina 🇦🇷
Validations: CVU/CBU format validation. Check digit validation. Bank deduced from account number. Alias supported.
Peru 🇵🇪
Validations: CCI format validation (20 digits). Bank deduced from account number.
Bolivia 🇧🇴
Validations: Bank deduced from account number.
United States 🇺🇸
Validations: Bank deduced from routing number. Generic bank saved if not found.
Verification Process
Automatic Verification: The bank account is automatically linked to your merchant’s registered business information. Ensure your merchant profile has the correct legal name and tax ID, as these will be used for account verification.
Listing Merchant Bank Accounts
Setting Up External Crypto Wallets
When You Need an External Crypto Wallet
✅ Required for:
- Receiving cryptocurrency from ONRAMP deals
- Sending crypto to your own custody solutions
- Long-term crypto holdings outside Koywe
Embedded Wallets vs External Wallets: Koywe provides embedded wallets automatically (via /wallet endpoint). External wallets are YOUR OWN wallets on hardware devices, exchanges, or other custody solutions where you want to receive crypto.
Adding an External Crypto Wallet
Supported Networks and Currencies
Network Matching Critical: When creating ONRAMP deals, the network parameter must match one of your registered external wallet networks. Always verify the network before sending crypto!
Listing External Crypto Wallets
Using External Accounts in Operations
ONRAMP: Send Crypto to External Wallet
When creating ONRAMP deals, specify your external wallet as the destination:
Use Embedded vs External: For operational crypto (frequent trading, OFFRAMP), use embedded wallets. For long-term holdings or specific custody requirements, use external wallets.
Withdrawals: Move Funds to External Bank Account
Request withdrawal from virtual account to your external bank account:
Automatic Settlements: If you have automatic settlements enabled, funds will be transferred to your primary external bank account automatically after the configured holding period. Manual withdrawals give you more control over timing.
Best Practices
Security
Always double-check crypto wallet addresses before adding them. Errors are irreversible.
Send small test transactions to new external wallets before large transfers.
Set up webhooks to track settlements and withdrawals to external accounts.
Maintain records of all external accounts for compliance and auditing.
Account Management
✅ Do:
- Keep primary accounts up to date
- Verify new accounts immediately
- Use separate wallets per network
- Document account purposes internally
❌ Don’t:
- Share account credentials
- Use exchange deposit addresses as external wallets (use withdrawal addresses)
- Add unverified or test wallets in production
- Use personal accounts for business operations
Common Patterns
Multi-Currency Setup
For businesses operating in multiple countries:
Multi-Network Crypto Setup
For diversified crypto holdings: