Frequently Asked Questions (FAQ)

Quick answers to common questions about Paysera Wallet API.

Quick Navigation

Use the tabs below to find answers by category. Click any question to expand the answer.

🔰 General

General Questions

What is Paysera Wallet API?

Paysera Wallet API enables you to:

• Get information about Paysera users and their accounts
• Make payments between Paysera accounts
• Manage user authentication (OAuth)
• Access wallet balances and transaction history
• Perform currency conversions

Key Features:

• OAuth 2.0 authentication
• User information access
• Payment processing
• Multi-currency support
• Allowances for recurring payments

📖 Getting Started →

What's the difference between Wallet API and Checkout API?

Feature	Wallet API	Checkout API
Purpose	P2P payments, user data	Accept payments from customers
Authentication	OAuth, MAC, SSL	Project ID + Password
Use case	Between Paysera users	E-commerce, invoices
Complexity	Advanced	Simple
User info	Full access	Limited

Choose Wallet API when:

• You need user authentication (Login with Paysera)
• You want to access user's wallet data
• You're building P2P payment features
• You need allowances for recurring charges

Choose Checkout API when:

• You're running an e-commerce store
• You want simple payment acceptance
• You need checkout pages
• You want plugin integration

Do I need a Paysera account?

Yes, you need:

1. Paysera business account
2. API client configured by Paysera
3. Signed agreement with Paysera
4. Production API credentials

📖 How to obtain credentials →

Is there a test environment?

No, Wallet API does not have a Sandbox environment.

Production Only

All integration and testing must be done in Production environment with real transactions. Plan your testing carefully with small amounts.

Production URL:

https://wallet.paysera.com/rest/v1

Recommendations:

• Start with small test amounts
• Test thoroughly before going live
• Implement proper error handling
• Use callbacks to track status

What currencies are supported?

Wallet API supports 20+ currencies including:

• EUR, USD, GBP, CHF
• PLN, CZK, RON, SEK,
• NOK, DKK
• And more...

Features:

• Multi-currency wallets
• Real-time currency conversion
• Competitive exchange rates

📖 Currency Conversion →

🔧 Integration

Integration Questions

What authentication methods are available?

Three authentication methods:

1. MAC Authentication

   • HMAC-based request signing
   • Most common method
   • Requires client_id and mac_key

2. SSL Certificate Authentication

   • Most secure method
   • Uses client SSL certificates
   • No shared secrets

3. OAuth 2.0

   • For user authentication
   • Access tokens
   • Refresh tokens

📖 Authentication Guide →

Which programming languages are supported?

Official libraries:

• ✅ PHP - Full featured library
• ✅ JavaScript - Client-side SDK

You can also:

• Use any language with HTTP client
• Implement MAC authentication yourself
• Use REST API directly

📖 Libraries & SDKs →

How long does integration take?

Typical timeline:

Feature	Time Required
OAuth authentication	2-4 hours
User information	1-2 hours
Basic payments	4-8 hours
Allowances	2-4 hours
Full integration	3-7 days

Actual time depends on your requirements and experience.

Can I use Wallet API with mobile apps?

Yes! Wallet API works with mobile apps.

Recommended architecture:

1. Mobile app initiates request
2. Your backend handles API calls
3. Backend returns results to app
4. Use OAuth for user authentication

Never:

• ❌ Store credentials in mobile app
• ❌ Make API calls directly from app
• ❌ Expose mac_key to clients

Use:

• ✅ Backend as proxy
• ✅ OAuth for user auth
• ✅ Access tokens for API calls

What is OAuth and when should I use it?

OAuth allows users to:

• Login with their Paysera account
• Grant access to their wallet data
• Authorize payments without passwords

Use OAuth when:

• Users need to login to your app
• You need access to user's wallet
• You want "Login with Paysera" feature
• You're building P2P payment features

OAuth flow:

1. Redirect user to Paysera
2. User logs in and grants permission
3. Get authorization code
4. Exchange code for access token
5. Use token to access API

📖 Getting Started →

💻 Technical

Technical Questions

What are OAuth scopes?

Scopes define what data you can access:

Scope	Access
user	User basic info
wallet_info	Wallet balances
wallet_history	Transaction history
wallet_pay	Make payments
currency_conversion	Currency exchange

Example request:

scope=user+wallet_info+wallet_pay

📖 User Information →

What is a transaction and how does it work?

Transaction groups one or more payments into confirmable unit.

Transaction lifecycle:

NEW → RESERVED → CONFIRMED
     ↓
   REJECTED/CANCELED

States:

• NEW - Just created, not yet confirmed
• RESERVED - Funds reserved, pending confirmation
• CONFIRMED - Payment completed
• REJECTED - User rejected
• CANCELED - Cancelled by system

📖 Making Payments →

What is an allowance?

Allowance = Permission to charge user without confirmation each time.

Use cases:

• Subscription payments
• Recurring charges
• Automatic top-ups
• Background payments

Example:

{
  "description": "Weekly subscription",
  "max_price": 1000, // €10
  "valid_for": 2592000 // 30 days
}

User grants allowance once, then you can charge automatically within limits.

📖 Transfer via Transition Account →

How do callbacks work?

Callbacks notify you about payment status changes.

When callbacks are sent:

• Transaction confirmed
• Transaction rejected
• Transaction cancelled
• Status updates

Requirements:

• Must be HTTPS
• Must be publicly accessible
• Should respond quickly (under 30 seconds)
• Must validate signature

📖 Making Your First Request →

What are projects, clients, and locations?

Organizational structure:

• Project - Main entity, has default account
• Client - API access credentials, belongs to project
• Location - Physical location (e.g., store, terminal)

Example:

Project: "MyShop"
├── Client 1: Web application
├── Client 2: Mobile app
└── Locations
    ├── Location 1: Store in Vilnius
    └── Location 2: Store in Kaunas

📖 Projects & Clients →

Can I perform currency conversion?

Yes! Currency conversion available.

Two-step process:

1. Calculate - Get exchange rate
2. Convert - Execute conversion

Example:

// 1. Calculate
POST /currency/calculate
{
  "amount_from": 10000,
  "currency_from": "EUR",
  "currency_to": "USD"
}

// 2. If rate is good, convert
POST /currency/convert
{
  "amount_from": 10000,
  "currency_from": "EUR",
  "currency_to": "USD"
}

📖 Currency Conversion →

⚠️ Troubleshooting

Troubleshooting

Getting "Invalid MAC signature" error

Common causes:

1. Wrong mac_key

   • ✓ Check credentials are correct
   • ✓ Verify you're using production credentials

2. Incorrect calculation

   • ✓ Check normalized request string
   • ✓ Verify parameter order
   • ✓ Check line endings (\n)

3. Wrong algorithm

   • ✓ Use hmac-sha-256
   • ✓ Base64 encode result

4. Clock skew

   • ✓ Sync server time
   • ✓ Check timestamp generation

Solution: Use official PHP library - it handles signing automatically!

📖 Authentication →

Transaction status stuck at "reserved"

Reasons:

1. Not confirmed

   • ✓ Call confirm endpoint
   • ✓ Check confirmation logic

2. Timeout

   • Transactions auto-cancel after timeout
   • Default: 30 minutes

3. Insufficient funds

   • Check wallet balance
   • Verify currency

Solution:

// Confirm transaction
PUT /transaction/{key}/confirm

"Access denied" or "Insufficient permissions"

Check:

1. OAuth scopes

   • ✓ Request correct scopes
   • ✓ User must grant permissions

2. Client permissions

   • ✓ Client must have required permissions
   • ✓ Contact Paysera to adjust

3. Project status

   • ✓ Project must be active
   • ✓ Check project settings

4. Wallet access

   • ✓ Verify wallet ID
   • ✓ User must own wallet

Callback is not validating signature

Validation steps:

1. Extract data and signature

   $data = $_GET['data'];
   $signature = $_GET['ss2'];

2. Decode data

   $decoded = base64_decode($data);

3. Calculate expected signature

   $expected = md5($data . $projectPassword);

4. Compare

   if ($signature !== $expected) {
       // Invalid!
   }

Common mistakes:

• Using wrong project password
• Wrong parameter name (ss1 vs ss2)
• Not Base64 decoding data

💰 Payments & Fees

Payments & Fees

What are the transaction fees?

Fees depend on:

• Your agreement with Paysera
• Transaction type
• Payment amount
• Currency

Typical fees:

• Paysera to Paysera: Low/free
• Incoming payments: Percentage-based
• Outgoing payments: May have fees

Contact Paysera for pricing:

• 📧 support@paysera.com
• 🌐 Paysera Business

How long do payments take?

Settlement times:

Payment Type	Time
Paysera → Paysera	Instant
Bank transfer	1-3 business days
Card payment	1-3 business days
International	3-5 business days

Factors:

• Payment method
• Bank processing
• Weekends/holidays
• First-time verification

Can I refund payments?

Yes, refunds available through:

1. Paysera web interface

   • Log in to account
   • Find transaction
   • Click refund

2. Contact support

   • For complex cases
   • Bulk refunds

Refund types:

• Full refund
• Partial refund

Note: Refunds may take 3-10 business days.

Are there payment limits?

Limits depend on:

• Wallet verification level
• User account type
• Transaction type

Typical limits:

• Unverified: Lower limits
• Verified personal: Higher limits
• Business: Highest limits

Check limits:

GET /wallet/{walletId}
// Response includes limit information

---

Support

Need help with complex integrations?

Contact: tech_support@paysera.com