Core Concepts Overview
Core Concepts
Before integrating with Koywe Payments, it’s important to understand the key concepts that form the foundation of our system.
The Hierarchy
Koywe Payments is built on a hierarchical structure that allows you to manage multiple business units and currencies efficiently:
This structure allows you to:
- Manage multiple business units (merchants) under one organization
- Maintain separate virtual accounts for each currency
- Track all transactions and orders per merchant
- Assign different permissions and access levels
Key Entities
Organizations
Your Organization is the top-level entity that represents your company in the Koywe system.
- One organization can contain multiple merchants
- Manages company-wide settings and users
- Controls API credentials and permissions
- Handles billing and reporting at the organization level
Learn more about Organizations →
Merchants
A Merchant represents an individual business unit or brand within your organization.
- Each merchant has its own virtual accounts
- Separate transaction tracking per merchant
- Independent payment processing
- Useful for multi-brand companies or franchises
Virtual Accounts
Virtual Accounts are multi-currency balance accounts that hold your funds within the Koywe system.
- One virtual account per currency per merchant
- Automatically created when you create a merchant
- Used for PAYIN, PAYOUT, and transfer operations
- Real-time balance tracking
Learn more about Virtual Accounts →
Contacts
Contacts represent your customers or providers in the system.
- Store customer/provider information
- Link bank accounts for payouts
- Track payment history
- Manage KYC/compliance data
Orders
Orders are the core transaction entities in Koywe Payments.
- Six order types: PAYIN, PAYOUT, BALANCE_TRANSFER, ONRAMP, OFFRAMP, PAYMENT_LINK
- Track payment status through lifecycle
- Link to contacts and virtual accounts
- Generate webhooks for status changes
Quotes
Quotes provide exchange rate locks for currency conversions.
- Get real-time exchange rates
- Lock rates for a specific time period
- Use in orders for transparent pricing
- Optional but recommended for customer transparency
How They Work Together
Example: Accepting a Payment
The flow:
- Your application creates an order for a specific Merchant
- The order links to a Contact (the customer)
- Customer pays using a Payment Method
- Funds are credited to the merchant’s Virtual Account
- You receive webhook notifications about the Order status changes
Example: Paying a Provider
The flow:
- Check your Virtual Account balance
- Create a PAYOUT order for a Contact (provider)
- Funds are debited from your Virtual Account
- Transferred to the provider’s bank account
- You receive webhook confirmation
Typical Integration Flow
When integrating Koywe Payments, you’ll typically follow these steps:
Understanding Order Types
Each order type serves a specific purpose in the payment flow:
Detailed guide for each order type →
Virtual Account Balance Flow
Understanding how money moves through virtual accounts:
Virtual accounts act as the central hub for all your payment operations:
- Receive funds from customer payments (PAYIN)
- Hold balances in multiple currencies
- Source for provider payments (PAYOUT)
- Source for crypto purchases (ONRAMP)
- Destination for crypto sales (OFFRAMP)
- Enable instant currency transfers
Data Relationships
Understanding how entities relate to each other:
Next Steps
Now that you understand the core concepts, dive deeper into each topic:
Learn how to structure your business units
Manage multi-currency balances
Store customer and provider information
Understand the six order types
Get and use exchange rate quotes
Try the 5-minute quickstart
