Projects, Clients & Locations

Learn about the core organizational concepts in Wallet API: how clients authenticate, how projects organize resources, and how locations enable physical interactions.

Core Concepts

Client

Your application or script that makes API requests. Each client has:

• Type - Defines capabilities and permissions
• Credentials - Authentication keys (MAC or SSL certificate)
• Permissions - What actions are allowed
• Project Association - Which project(s) it represents

Project

A project represents a business entity or service. Each project has:

• Owner - The user/company that owns it
• Default Account - For receiving payments
• Wallet - Associated payment wallet
• Multiple Clients - Can be accessed by different clients

Location

Physical places where Paysera services are available. Locations have:

• Address & GPS - Physical location data
• Services - Available operations (cash-in, cash-out, payments)
• Working Hours - When services are available
• Project Association - Belongs to a specific project

---

Client Types

Understanding client types is crucial for choosing the right integration approach.

1. Private Client (private_client)

Best for: Server-to-server integrations, backend systems

Characteristics:

• Can manage one or multiple projects
• Based on web or offline location
• Not accessible by 3rd parties
• Full API access with proper permissions

Use Cases:

• E-commerce backend integration
• Administrative dashboards
• Payment processing systems
• Automated financial operations

2. Application Client (application)

Best for: Mobile application SDKs

Characteristics:

• Related to single project
• Credentials bundled in app package
• Limited to client registration operations
• Creates app_client instances per device

Use Cases:

• Mobile app SDK initialization
• Device-specific client creation
• First-time app setup

3. App Client (app_client)

Best for: Individual device installations

Characteristics:

• Created by application client
• Unique per device
• Isolated from other devices
• Enhanced per-device security

Use Cases:

• Individual mobile app instances
• Device-specific operations
• Secure multi-device support

---

Client Type Comparison

Feature	Private Client	Application	App Client
Use Case	Backend/Server	Mobile SDK	Per Device
Projects	Multiple	Single	Single
Full API Access	✅ Yes	❌ Limited	✅ Yes
Creates Clients	❌ No	✅ Yes	❌ No
Credential Location	Server	App Package	Per Device
Best For	Server systems	App initialization	App instances

---

Project Structure

Key Points:

• One project can have multiple clients
• application client creates app_client instances
• All clients share the same project resources
• Each has different permissions/capabilities

---

Location Services

Locations enable physical interactions with Paysera services.

Available Services

💰 Cash In Deposit cash into Paysera account

Types:

• contact - With email/phone verification
• bar_code - Using multi-use barcode
• document - With ID verification
• one_time_bar_code - Single-use barcode

💵 Cash Out Withdraw cash from Paysera account

Types:

• qr_code - Using QR code
• document - With ID verification

💳 Pay Make payments with Paysera account

Features:

• Category-based locations
• Working hours
• Special offers/prices

🆔 Identification User identity verification service

---

Extra Parameters

Some API requests may include extra parameters for context.

project_id Parameter

When to use:

• Client manages multiple projects
• Access token has projects scope
• Need to specify which project

How to pass:

MAC Authentication:

Authorization: MAC id="...", ..., ext="project_id=123"

SSL Certificate:

Wallet-Api-Project-Id: 123

location_id Parameter

When to use:

• Payment initiated at specific location
• Need location context for transaction

Benefits:

• Influences allowance usage
• Provides location info to user
• Better transaction tracking

How to pass:

MAC Authentication:

Authorization: MAC id="...", ..., ext="location_id=456"

SSL Certificate:

Wallet-Api-Location-Id: 456

---

Quick Start

For Backend Integration (Private Client)

1. Get Credentials from Paysera support
2. Implement Authentication (MAC or SSL)
3. Start Making Requests with your client

const client = new PayseraClient({
    clientId: 'your_client_id',
    macKey: 'your_mac_key'
});

// Get current client info
const info = await client.getClientInfo();
console.log(info.permissions);

For Mobile App (Application Client)

1. Register Application with Paysera
2. Bundle Credentials in app package
3. Create Device Clients on first run

// First run - create app_client
const appClient = await applicationClient.createClient({
    type: 'app_client',
    info: {
        device_id: deviceId,
        os: 'Android 13',
        model: 'Samsung Galaxy S23'
    }
});

// Store credentials
await storage.save({
    accessToken: appClient.credentials.access_token,
    macKey: appClient.credentials.mac_key
});

---

Key API Methods

Get Current Client Info

GET /rest/v1/client

Returns permissions, type, and configuration.

---

Create New Client (Application Only)

POST /rest/v1/client

Creates app_client for device.

---

Get Project Information

GET /rest/v1/project/{projectId}

Returns project details and associated wallet.

---

Get User's Projects

GET /rest/v1/user/me/projects

Lists projects user can administer.

---

Get Nearby Locations

GET /rest/v1/locations?lat=54.6&lng=25.2&distance=1000

Find locations within distance from coordinates.

---

What's Next?

1. 📱 Client Types & Management - Detailed client documentation
2. 📊 Project Management - Working with projects
3. 📍 Location Services - Using physical locations
4. 🔐 Authentication - Setup authentication

---

Need Help?

• API Support: tech_support@paysera.com
• Project Setup: Contact Paysera support for client configuration
• Documentation: API Reference