Skip to main content
Create multiple merchant accounts, profiles and users for seamless integration with your business using PesaSwap. If there are more than one business_profiles for a merchant account, then passing profile_id when creating a payment is mandatory. PesaSwap architecture supports:
  • Creating multiple merchant accounts under an organization (Organization → Merchant → Profile model)
  • Creating multiple business profiles under each merchant account
  • Creating multiple instances of payment processors (, M-Pesa, Airtel Money, etc.) under each business profile
Additionally, with the new Platform Org and Merchant model, you can:
  • Programmatically onboard sub-merchant accounts via API (under a PlatformOrg)
  • Automatically generate and manage API keys for each sub-merchant
  • Maintain centralized visibility and control over payments, refunds, and settlements across all sub-merchants

​
1. Organization → Merchant → Profile Model

Here’s how the PesaSwap architecture works: 
Organization (PesaSwap Business)
├── Merchant Account 1 (E-commerce Store)
│   ├── Business Profile 1 (Electronics)
│   │   ├── M-Pesa Connector
│   │   ├── Airtel Money Connector
│   │   ├── Tigo Pesa Connector
│   │   └── PayPal Connector
│   └── Business Profile 2 (Clothing)
│       ├── M-Pesa Connector
│       ├── Airtel Money Connector
│       └── Stripe Connector
└── Merchant Account 2 (Marketplace)
    ├── Business Profile 1 (Vendors)
    │   ├── M-Pesa Connector
    │   └── Airtel Money Connector
    └── Business Profile 2 (Services)
        ├── M-Pesa Connector
        └── PayPal Connector

​
Understanding the Hierarchy

​
Organization

Organization refers to the main business entity. When a new user registers with PesaSwap, an organization is created and the user assumes the role of organization admin.

​
Merchant Account

A merchant account is associated with an api_key and publishable_key which is used for authentication. Multiple merchant accounts can be created under an organization by an organization admin.

​
Profile

Every merchant account has at least one profile. For easier integration, profile_id is not mandatory if there is only one business profile. A profile serves as a business profile for practical purposes, providing logical separation of businesses for seamless integration and onboarding. Every business profile is uniquely identified by a profile_id. All payment settings can be configured at the profile level and will apply to all payments made via the business profile. If there is more than one business profile, then profile_id must be passed when creating payments. Business profile allows you to configure:
  • Roles and permissions for users can be assigned at the organization level and merchant level
  • Routing Algorithm - Only gateways available under the business profile can be used to configure the routing algorithm
  • Default fallback - If a routing algorithm is not available, a default fallback consisting of all processors configured under the business profile based on priority order will be used
  • Webhook URL and Return URL for payments
  • Mobile money integration settings for M-Pesa, Airtel Money, Tigo Pesa
  • Pesaswap configuration for card payments and digital wallets

​
Processors

Multiple processors can be configured under a business profile. Each processor is associated with a globally unique identifier merchant_connector_id and unique identifier under a business profile called label. A processor created under one business profile cannot be used in another business profile to route payments. Supported Payment Processors:
  • Pesaswap - Primary payment gateway for card payments, digital wallets
  • M-Pesa - Mobile money payments
  • Airtel Money - Mobile money payments
  • Tigo Pesa - Mobile money payments
  • PayPal - International payments
  • Stripe - International card payments
  • Flutterwave - African payment solutions

​
2. Use Cases

​
Multiple Merchant Accounts

For merchants who need different API keys for each of their businesses. Example: Merchant A has three different businesses - A_Electronics, A_Clothing, A_Services. They can create three merchant accounts (Electronics, Clothing, Services) on PesaSwap and get separate sets of API keys for each. 
Organization: A_Business
├── Merchant Account: A_Electronics (API Key: pk_electronics_xxx)
│   └── Profile: Default
├── Merchant Account: A_Clothing (API Key: pk_clothing_xxx)
│   └── Profile: Default
└── Merchant Account: A_Services (API Key: pk_services_xxx)
    └── Profile: Default
Marketplace Use Case: For marketplace merchants with multiple sub-merchants, the parent merchant can create one PesaSwap merchant account (with an API key) for themselves and separate merchant accounts for sub-merchants with individual API keys.

​
Multiple Business Profiles

For merchants who want to manage all businesses with one API key. Example: Merchant A with three different businesses (A_Electronics, A_Clothing, A_Services) can create one merchant account on PesaSwap with three business profiles under it. This allows the merchant to use only one PesaSwap API key to manage transactions for all three businesses. 
Organization: A_Business
└── Merchant Account: A_Business (API Key: pk_business_xxx)
    ├── Profile: Electronics (profile_id: prof_electronics_xxx)
    ├── Profile: Clothing (profile_id: prof_clothing_xxx)
    └── Profile: Services (profile_id: prof_services_xxx)
Marketplace Use Case: Parent merchants can create one PesaSwap merchant account with multiple business profiles to represent different sub-merchants, managing them under one API key.

​
3. Configuration Guide

​
How to Configure Multiple Merchant Accounts

When you sign up on PesaSwap, a merchant account and profile are created under your organization account by default. To create more merchant accounts:
  1. Click the merchant account dropdown from the top left corner in your PesaSwap dashboard
  2. Click on “Create New Merchant” option
  3. Enter merchant details including business name, type, and contact information
  4. Configure payment methods (Pesaswap, M-Pesa, Airtel Money, etc.)
  5. Generate API keys for the new merchant account

​
How to Configure Multiple Business Profiles

To create more profiles:
  1. Click the profile dropdown from the top right corner in your PesaSwap dashboard
  2. Click on “Create New Profile” option
  3. View list of already configured business profiles for your merchant account
A ‘default’ profile is created during merchant account creation. profile_id of various business profiles can be found under Settings → Business Profiles. Steps:
  1. Enter a name for your profile in the pop-up screen
  2. Select payment methods to enable (Pesaswap, M-Pesa, Airtel Money, etc.)
  3. Configure webhook URLs and return URLs
  4. Set up routing preferences
  5. Click ‘Add’ to create the profile
A new profile with the given profile_name and automatically generated profile_id is created.

​
How to Route a Payment to a Particular Merchant Account and Profile

To route a payment to a specific merchant account, the payment create API call must be made from the merchant server using the correct API key attached to the required merchant account. To route the payment to a particular profile, pass the profile_id parameter of the required profile. API Key Authentication: 
POST /payments
Headers:
  Authorization: Bearer pk_your_api_key_here
  Content-Type: application/json
Profile ID in Request Body: 
{
  "amount": 10000,
  "currency": "TZS",
  "profile_id": "prof_electronics_xxx",
  "payment_method": "mobile_money",
  "mobile_money": {
    "provider": "mpesa",
    "phone_number": "+255123456789"
  }
}
When a payment is created under a business profile, it uses the routing algorithm (if available) configured for that business profile to choose an appropriate gateway. All Refunds and Mandates created for a payment will be under the same business profile as the payment.

​
4. Payment Method Configuration

​
Pesaswap Integration

Configure Pesaswap for card payments and digital wallets: 
{
  "connector": "pesaswap",
  "label": "pesaswap_primary",
  "configuration": {
    "merchant_id": "your_pesaswap_merchant_id",
    "api_key": "your_pesaswap_api_key",
    "environment": "production",
    "supported_payment_methods": ["card", "netbanking", "wallet"]
  }
}

​
M-Pesa Integration

Configure M-Pesa for mobile money payments: 
{
  "connector": "mpesa",
  "label": "mpesa_tanzania",
  "configuration": {
    "business_short_code": "174379",
    "consumer_key": "your_consumer_key",
    "consumer_secret": "your_consumer_secret",
    "passkey": "your_passkey",
    "environment": "production"
  }
}

​
Airtel Money Integration

Configure Airtel Money for mobile payments: 
{
  "connector": "airtel_money",
  "label": "airtel_primary",
  "configuration": {
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "merchant_id": "your_merchant_id",
    "environment": "production"
  }
}

​
5. API Examples

​
Create Payment with Profile ID

POST /api/v1/payments
Headers:
  Authorization: Bearer pk_your_api_key
  Content-Type: application/json

Body:
{
  "amount": 50000,
  "currency": "TZS",
  "profile_id": "prof_electronics_xxx",
  "payment_method": "mobile_money",
  "mobile_money": {
    "provider": "mpesa",
    "phone_number": "+255123456789"
  },
  "description": "Electronics purchase",
  "return_url": "https://pesaswap.io/payment/return",
  "webhook_url": "https://pesaswap.io/webhooks/payment"
}

​
Create Refund

POST /api/v1/refunds
Headers:
  Authorization: Bearer pk_your_api_key
  Content-Type: application/json

Body:
{
  "payment_id": "pay_xxx",
  "amount": 25000,
  "reason": "Product return",
  "profile_id": "prof_electronics_xxx"
}

​
6. Best Practices

  1. Use Profiles for Business Separation - Create separate profiles for different business units or product categories
  2. Configure Multiple Payment Methods - Enable both Pesaswap and mobile money options for maximum coverage
  3. Set Up Proper Routing - Configure routing algorithms to optimize success rates and costs
  4. Monitor Performance - Use PesaSwap dashboard to track performance across profiles
  5. Secure API Keys - Never expose API keys in client-side code
  6. Test Thoroughly - Use sandbox environment for testing before going live
  7. Configure Webhooks - Set up webhooks for real-time payment status updates

​
7. Troubleshooting

​
Common Issues

Payment Method Not Available:
  • Check if the payment method is configured for the specific profile
  • Verify processor configuration is complete
Authentication Errors:
  • Verify API key is correct and active
  • Check if API key has permissions for the requested action
For additional support, contact PesaSwap technical support at info@pesaswap.io or visit our developer portal at docs.pesaswap.io