API Fundamentals

Learn how the Wallet API works, including request/response formats, error handling, client types, and core API methods.

REST Principles

The Wallet API is based on REST (Representational State Transfer) principles.

HTTP Methods:

Method	Purpose	Example Use Case
GET	Retrieve information	Get wallet balance, user details
POST	Create new resources	Create payment, register client
PUT	Update existing resources	Update user information
DELETE	Remove resources	Cancel payment, delete resource

Request & Response Format:

• Content Type: JSON (UTF-8 encoding)
• Success Status: 200 - Request successful
• Error Status: Various codes (see error section)
• Optional Fields: May be omitted entirely (not returned as null)

Handling Optional Fields

Don't assume optional elements will always exist. Always check for their presence before accessing them.

---

Errors and Response Codes

Standard Error Codes:

Error Code	Status	Description
invalid_request	400	Request content is invalid
invalid_parameters	400	Required parameter missing or format invalid
invalid_state	409	Action cannot be performed in current state
unauthorized	401	Authentication missing or incorrect
forbidden	403	No permission for resource/action
not_found	404	Resource not found
internal_server_error	500	Unexpected system error
not_acceptable	406	Unknown request/response format

Error Object Structure & Example

Error Object Structure:

Parameter	Type	Always Present	Description
error	string	✅ Yes	Error code identifier
error_description	string	⚠️ Sometimes	Human-readable error description
error_uri	string	⚠️ Sometimes	Link to documentation or help

Error Response Example:

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=utf-8

{
    "error": "forbidden",
    "error_description": "This resource is assigned to other project, client has no rights to read it"
}

---

Client Types and Permissions

Different Client Types

Available Client Types:

1. Private Client (private_client)

Purpose: Web or offline location-based client

Characteristics:

• Can manage one or multiple projects
• Based on web or offline location
• Not accessible by 3rd party persons
• Most flexible permissions

Best for: Server-to-server integrations, Backend systems, Administrative tools

2. Application Client (application)

Purpose: Mobile application integration

Characteristics:

• Related to one specific project
• Credentials integrated into app package
• Limited to Client resource operations only
• Can register new app clients

Best for: Mobile application SDKs, Client app initialization

3. App Client (app_client)

Purpose: Device-specific client

Characteristics:

• Created dynamically by application client
• Unique per device installation
• Isolated - cannot access other devices' data
• Enhanced security per device

Best for: Individual mobile app installations, Device-specific operations

Client Type Comparison:

Feature	Private Client	Application	App Client
Projects	Multiple	Single	Single
Location	Web/Offline	Mobile	Mobile (device)
Credentials	Server-side	In app package	Per device
Scope	Full API	Limited	Device-specific

---

Extra Parameters

project_id and location_id Parameters

Available Parameters:

project_id:

• Purpose: Defines the specific project
• When to use: Client manages multiple projects or using access token with projects scope

location_id:

• Purpose: Defines the specific physical location
• When to use: Payment initiated at specific location
• Benefits: Influences allowance usage, provides location details in payment info

How to Pass Extra Parameters:

MAC Access Authentication:

Include parameters in the ext authentication field:

Authorization: MAC id="wkVd93h2uS", ts="1343811600", 
    nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", 
    mac="EOhN6gBf49tR2KxMflaaiN7bBVGDhfG6co8gcSBLyiQ=", 
    ext="project_id=3"

SSL Client Certificate:

Pass as separate HTTP headers with Wallet-Api- prefix:

Wallet-Api-Project-Id: 3
Wallet-Api-Location-Id: 5

---

Essential API Methods

Getting Server Time:

Retrieve current server time to synchronize clocks.

No Authentication Required

GET /rest/v1/server

Response:

{
    "time": 1383116734
}

Use Cases: Clock synchronization, Mobile phone time verification

Getting Server Configuration:

Retrieve server configuration variables.

No Authentication Required

GET /rest/v1/configuration

Response:

{
    "minimum_password_length": 8
}

Use Cases: Password validation requirements, Client-side validation

---

What's Next?

1. 🔐 Learn Authentication - Implement secure authentication
2. 🔒 Review Security - Security best practices
3. 📖 API Endpoints - See all available methods
4. 💡 Code Examples - Practical implementations

---

Response Formats

All API responses are in JSON format with UTF-8 encoding.

Success Response Structure:

Status Code: 200 OK

{
    "field1": "value",
    "field2": 123,
    "nested": {
        "field3": true
    }
}

Important Response Rules:

1. Optional Fields: If optional field has no value, it's omitted entirely (not returned as null)
2. Null Values: Never returned - field is simply not present
3. Empty Arrays: Returned as [] (not omitted)
4. Boolean Fields: Always true or false (never null)

Example:

{
    "id": 123,
    "name": "John",
    // phone is optional and not set - field omitted
    "verified": true,
    "tags": []  // empty array still returned
}

Pagination

For endpoints returning lists, pagination is supported using offset-based or cursor-based methods.

Offset-Based Pagination:

Query Parameters:

• limit (integer) - Number of items per page (default: 20, max: 200)
• offset (integer) - Number of items to skip (default: 0)

Example Request:

GET /rest/v1/transactions?limit=50&offset=100

Response:

{
    "transactions": [...],
    "_metadata": {
        "total": 65,
        "limit": 50,
        "offset": 100
    }
}

Advanced Error Handling

HTTP Status Code Summary:

Status	Category	Meaning	Action
200	Success	Request successful	Process response
400	Client Error	Bad request	Fix request parameters
401	Client Error	Not authenticated	Check credentials
403	Client Error	No permission	Check permissions
404	Client Error	Not found	Check resource ID
409	Client Error	Conflict	Check resource state
429	Client Error	Rate limited	Wait and retry
500	Server Error	Internal error	Retry with backoff

Error Handling Strategy:

async function handleApiError(error) {
    const { status, data } = error.response;
    
    switch (status) {
        case 400:
            console.error('Invalid request:', data.error_description);
            // Log details and fix request
            break;
            
        case 401:
            console.error('Authentication failed');
            // Refresh token or re-authenticate
            await refreshAuthentication();
            break;
            
        case 403:
            console.error('Permission denied:', data.error_description);
            // Check required permissions
            break;
            
        case 404:
            console.error('Resource not found');
            // Verify resource ID
            break;
            
        case 429:
            const retryAfter = error.response.headers['retry-after'];
            console.log(`Rate limited. Retry after ${retryAfter}s`);
            await sleep(retryAfter * 1000);
            // Retry request
            break;
            
        case 500:
            console.error('Server error. Retrying...');
            // Retry with exponential backoff
            await retryWithBackoff();
            break;
            
        default:
            console.error('Unexpected error:', status, data);
    }
}

---

Need Help?

• API Support: tech_support@paysera.com
• Documentation: Endpoint documentation
• Examples: Code examples