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

Learn more about Merchants →

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

Learn more about Contacts →

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

Learn more about Orders →

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

Learn more about Quotes →

How They Work Together

Example: Accepting a Payment

The flow:

1. Your application creates an order for a specific Merchant
2. The order links to a Contact (the customer)
3. Customer pays using a Payment Method
4. Funds are credited to the merchant’s Virtual Account
5. You receive webhook notifications about the Order status changes

Example: Paying a Provider

The flow:

1. Check your Virtual Account balance
2. Create a PAYOUT order for a Contact (provider)
3. Funds are debited from your Virtual Account
4. Transferred to the provider’s bank account
5. 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: