Payment Concepts

Understanding core payment concepts will help you effectively integrate Paysera Wallet payments into your application.

Quick Links

• Already familiar? → Jump to Samples & Examples
• Need API details? → Check Payment Resource in API Resources section (see sidebar)

Core Payment Components

The Wallet API payment system consists of four main components that work together:

Let's explore each component in detail.

💼 1. Wallet

Definition: A wallet is always related to a specific user and account. It's the fundamental entity for making and receiving payments.

Key Characteristics:

• 🔗 User-specific: Each wallet belongs to exactly one user
• 💰 Account-linked: Connected to a specific account with balance
• 📱 Multiple per user: Users can have several wallets
• 🎯 Different limits: Each wallet can have unique transaction limits
• 💳 Card-linkable: Can be associated with payment cards or other identifiers

Wallet Types

Wallet Type	Purpose	Example
Main Wallet	Primary account	Daily transactions
Savings Wallet	Long-term storage	Savings account
Card-linked Wallet	Card payments	Specific payment card
Business Wallet	Company account	Business expenses

Example

{
  "id": 14471,
  "owner": 12345,
  "account": "EVP1234567890",
  "currency": "EUR",
  "limits": {
    "max_payment": 50000,
    "daily_limit": 100000
  }
}

→ Learn more: Wallet Resource

💸 2. Payment

Definition: A transfer of funds from one wallet (payer) to another wallet (beneficiary).

Payment Structure

Payment Types

Simple Payment - Basic price-only payment:

{
  "description": "Service payment",
  "price": 2999,
  "currency": "EUR"
}

Itemized Payment - Detailed item breakdown:

{
  "description": "Shopping cart",
  "items": [
    {
      "title": "Product A",
      "price": 1499,
      "quantity": 2,
      "image_uri": "https://example.com/product-a.jpg"
    },
    {
      "title": "Product B",
      "price": 999,
      "quantity": 1
    }
  ]
}

Beneficiary Options

Method	When to Use	Example
Wallet ID	You know beneficiary's wallet	beneficiary_id: 14471
Email	User not registered yet	email: "user@example.com"
Phone	Mobile-based payment	phone: "+37060000000"

Unregistered Beneficiaries

If beneficiary email/phone isn't registered, they'll receive instructions to register and claim the payment.

📦 3. Transaction

Definition: A container that groups one or more payments (and optionally an allowance) into a single confirmable unit.

Why Transactions?

1. Atomic Operations: All payments succeed or all fail together
2. Single Confirmation: User confirms once for multiple payments
3. Coordinated Payments: Perfect for split payments or multi-party transactions
4. State Management: Track the entire payment process

Transaction Composition

Example: Shopping Cart

Multiple items going to different sellers:

{
  "payments": [
    {
      "description": "Item from Seller A",
      "price": 2500,
      "beneficiary_id": 11111
    },
    {
      "description": "Item from Seller B", 
      "price": 1500,
      "beneficiary_id": 22222
    }
  ],
  "redirect_uri": "https://yoursite.com/payment-return"
}

Result: User confirms once, both sellers receive their payments atomically.

🔄 4. Allowance

Definition: Permission to charge a wallet automatically without user interaction for each payment, as long as limits aren't exceeded.

How Allowances Work

Allowance Limits

Total Limit

{
  "max_price": 5000,  // Max 50 EUR total
  "valid_for": 2592000  // Valid for 30 days
}

Time-Based Limits

{
  "max_price": 10000,  // 100 EUR total
  "limits": [
    {
      "max_price": 2000,   // Max 20 EUR
      "time": 604800       // per week (7 days)
    }
  ]
}

Common Use Cases

Use Case	Limit Strategy
Monthly Subscription	Max €9.99/month for 12 months
Usage-Based Billing	Max €50/month, renews monthly
Microtransactions	Max €1 per transaction, €10/day
Service Credits	Max €100 total, no time limit

Allowance Lifecycle

1. Created - Allowance request created
2. Accepted - User confirms allowance
3. Active - Can be used for payments
4. Expired - Time limit reached
5. Canceled - Manually canceled or limit exhausted

Important

• Only one active allowance per wallet/client combination
• Creating new allowance cancels the previous one (when confirmed)
• Allowance doesn't guarantee sufficient balance

💵 5. Commission

Definition: An additional fee or charge associated with a payment.

Outgoing Commission

Fee paid by payer (added to payment amount):

{
  "payment": {
    "price": 10000,  // 100 EUR to beneficiary
    "commission": {
      "out_commission": 500  // + 5 EUR fee from payer
    }
  }
}

Total charged from payer: 105 EUR
Beneficiary receives: 100 EUR

Incoming Commission

Fee deducted from beneficiary (subtracted from payment):

{
  "payment": {
    "price": 10000,  // 100 EUR payment
    "commission": {
      "in_commission": 300  // - 3 EUR fee to beneficiary
    }
  }
}

Payer pays: 100 EUR
Beneficiary receives: 97 EUR

---

Payment Flow Comparison

View Payment Flows

One-Time Payment

Create → User Confirms → Transfer Complete
   ↓           ↓              ↓
  NEW      WAITING         DONE

User action: Required for each payment
Best for: E-commerce, one-time purchases

Allowance Payment

Setup Allowance → Automatic Payments → Transfer Complete
       ↓                  ↓                  ↓
   ACTIVE         AUTO-CHARGED            DONE

User action: Once during setup
Best for: Subscriptions, recurring charges

---

What's Next?

Now that you understand the concepts:

1. Transaction Flow - Learn the complete payment lifecycle
2. Samples & Examples - See practical payment implementations
3. Payment Resource - Explore the API (see API Resources in sidebar)
4. Transaction Resource - Manage transactions (see API Resources in sidebar)

---

Need Help?

• Questions? → tech_support@paysera.com
• API Reference → Wallet API Endpoints
• Examples → Code Samples

Quick Reference

Keep this page bookmarked - it's a handy reference for payment terminology and concepts!