Wallet Resource

Work with wallets, balances, statements, transactions, and payments.

Overview

The Wallet Resource provides methods for managing wallet data.

Quick Reference

Feature	Endpoints	Required Scope	Description
Get Wallet	GET /wallet/:id	-	Retrieve wallet details
Check Balance	GET /wallet/:id/balance	balance	Get balance by currency
Sufficient Check	GET /wallet/:id/sufficient-amount	check_has_sufficient_balance	Check if enough funds
Statements	GET /wallet/:id/statements	statements	Transaction history
Reservations	GET /wallet/:id/reservation-statements	statements	Reserved funds
Pending Payments	GET /wallet/:id/pending-payments	incoming/outgoing_payments	Manage pending
Favourites	GET /wallet/:id/favourites	favourites	Common beneficiaries
Update Description	PUT /wallet/:id	manage_account	Account description
Search Wallets	GET /wallets?email=...	-	Find multiple wallets
Card Management	PUT /wallet/:id/card	Special permission	Relate cards

→ Full scope list: Available Scopes

---

Get Wallet Information

Retrieve wallet information by ID or other identifiers.

By Wallet ID

GET /rest/v1/wallet/:id

Parameters:

• id - Wallet ID (integer) or me (with access token)

By Other Information

GET /rest/v1/wallet?phone=:phone&email=:email&account_number=:number

Query Parameters:

• phone - User's phone (country code, no 00/+)
• email - User's email address
• account_number - Account number
• person_code[:nationality] - Person code with nationality
• company_code[:country] - Company code with country
• barcode - Wallet barcode
• licence_plate - Car license plate
• card[:issuer] - Card number with issuer
• user_id - User ID

Only One Parameter

Only one parameter can be passed to search by that specific criteria.

📋 Response Structure & Example

Response Fields

Field	Type	When Available	Description
id	integer	Always	Wallet ID
owner	integer	Always	User ID who owns wallet
account	object	Always	Account information

Account Structure

Field	Type	When Available	Description
number	string	Always	Account number
owner_display_name	string	With wallet_list scope	Owner display name
owner_title	string	With wallet_list scope	Confirmed owner title
description	string	With wallet_list scope	Custom account description
user_id	integer	With wallet_list scope	Account owner user ID
type	string	With wallet_list scope	local, technical, or card
ibans	array	If IBAN available	Related IBAN accounts

Example Response

{
    "id": 14471,
    "owner": 221,
    "account": {
        "number": "EVP0010001000101",
        "owner_display_name": "John Smith",
        "owner_title": "John Smith",
        "description": "My personal account",
        "user_id": 221,
        "type": "local",
        "ibans": ["LT007300010022221111"]
    }
}

---

Get Wallet Balance

Retrieve balance information across all currencies (requires balance or balance_offline scope).

GET /rest/v1/wallet/:walletId/balance?convert_to=:currency&show_historical_currencies=:boolean

Parameters:

• walletId - Wallet ID or me
• convert_to - Optional: Convert all to specific currency
• show_historical_currencies - Optional: Show zero-balance currencies

💰 Response Structure & Examples

Response Format

Response object with currency codes as keys:

{
    "EUR": {
        "at_disposal": 2299,
        "at_disposal_decimal": "22.99",
        "reserved": 0,
        "reserved_decimal": "0"
    },
    "USD": {
        "at_disposal": 100,
        "at_disposal_decimal": "1.00",
        "reserved": 9800,
        "reserved_decimal": "98.00"
    }
}

With Currency Conversion

{
    "EUR": {
        "at_disposal": 2299,
        "at_disposal_decimal": "22.99",
        "reserved": 0,
        "reserved_decimal": "0",
        "converted": {
            "at_disposal": 2299,
            "at_disposal_decimal": "22.99"
        }
    },
    "USD": {
        "at_disposal": 100,
        "at_disposal_decimal": "1.00",
        "reserved": 9800,
        "reserved_decimal": "98.00",
        "converted": {
            "at_disposal": 75,
            "at_disposal_decimal": "0.75",
            "reserved": 7339,
            "reserved_decimal": "73.39"
        }
    }
}

Balance Receipt

GET /rest/v1/wallet/:walletId/receipt/balance?locale=:locale&width=:width

Returns text receipt for printing (requires special permissions).

---

Advanced Features

✅ Check Sufficient Balance

Check if wallet has enough funds (requires check_has_sufficient_balance scope).

GET /rest/v1/wallet/:walletId/sufficient-amount?amount=:cents&currency=:code

Parameters:

• walletId - Wallet ID or me
• amount - Amount in cents
• currency - Currency code

Response:

{
    "is_sufficient": true
}

📊 Get Wallet Statements

Retrieve transaction history (requires statements or statements_offline scope).

GET /rest/v1/wallet/:id/statements?currency=:cur&from=:timestamp&to=:timestamp&limit=:num&offset=:num

Query Parameters

Parameter	Type	Description
currency	string	Currency list (comma-separated)
direction	string	in or out
text	string	Search in statement details
from	integer	UNIX timestamp (default: week before to)
to	integer	UNIX timestamp (default: now)
limit	integer	Max results (1-200, default: 20)
offset	integer	Skip count (default: 0)
after	string	Cursor for next page
before	string	Cursor for previous page

PSD2 Rate Limits

For PSD2 clients: 4 requests per 4 minutes OR 50 per day. Exceeds cause rate_limit_exceeded error.

Response Format

{
    "statements": [
        {
            "id": 59418,
            "amount": 100,
            "currency": "EUR",
            "amount_decimal": "1.00",
            "direction": "in",
            "date": 1363340355,
            "details": "Currency exchange",
            "type": "currency",
            "transfer_id": 45375,
            "other_party": {
                "display_name": "John Smith",
                "wallet_id": 78441,
                "account_number": "EVP..."
            }
        }
    ],
    "_metadata": {
        "total": 150,
        "offset": 0,
        "limit": 20
    }
}

Statement Types: transfer, commission, cash, currency, tax, return, automatic_payment, card_transaction

🔒 Get Reservation Statements

View reserved funds and pending transactions (requires statements scope).

GET /rest/v1/wallet/:id/reservation-statements

Response Format

{
    "reservation_statements": [
        {
            "type": "transfer_out",
            "amount": 100,
            "currency": "EUR",
            "details": "Transfer to John",
            "date": 1373449733,
            "transfer_id": 12345,
            "other_party": {
                "display_name": "John Smith",
                "account_number": "LT..."
            }
        }
    ],
    "_metadata": {
        "total": 2,
        "offset": 0,
        "limit": 50
    }
}

Reservation Types: transfer_out, transfer_in, hold, credit_card_pending_transaction

⏳ Pending Payments

Manage incoming and outgoing pending payments.

GET /rest/v1/wallet/:walletId/pending-payments?type=:type&direction=:direction&limit=:num

Parameters:

• type - Optional: password (currently only type)
• direction - Optional: in or out
• limit - Max results (1-200, default: 20)

Required Scopes

• incoming_payments - For in direction
• outgoing_payments - For out direction

Response Format

{
    "pending_payments": [
        {
            "id": 59418,
            "amount": 100,
            "currency": "EUR",
            "amount_decimal": "1.00",
            "details": "Payment with password",
            "type": "password",
            "direction": "in",
            "cancelable": true,
            "date": 1363340355,
            "valid_until": 1363426755,
            "other_party": {
                "wallet_id": 78441,
                "user_id": 44587,
                "display_name": "John Smith"
            }
        }
    ]
}

Provide Password

PUT /rest/v1/wallet/:walletId/pending-payment/:paymentId

{
    "password": "secret123"
}

Rate Limit

Maximum 10 password requests per hour.

Cancel Payment: DELETE /rest/v1/wallet/:walletId/pending-payment/:paymentId

⭐ Get Favourites

Get most common payment beneficiaries (requires favourites or favourites_offline scope).

GET /rest/v1/wallet/:walletId/favourites?limit=:num&offset=:num

Response Format

{
    "favourites": [
        {
            "payment_count": 5,
            "user_info": {
                "wallet_id": 4558,
                "account_number": "EVP7010001000101",
                "user_id": 54,
                "display_name": "John Smith",
                "phone": "37066612345",
                "email": "john@example.com"
            }
        }
    ],
    "_metadata": {
        "total": 10,
        "offset": 0,
        "limit": 20
    }
}

📝 Account Description Management

Update or delete account descriptions (requires manage_account scope).

Update Description

PUT /rest/v1/wallet/:walletId

{
    "description": "My savings account"
}

Delete Description: DELETE /rest/v1/wallet/:walletId/description

🔍 Search Wallets

Search for multiple wallets by various identifiers.

GET /rest/v1/wallets?email=:emails&phone=:phones&email_hash=:hashes&phone_hash=:hashes

Parameters (comma-separated lists):

• email - Email addresses
• phone - Phone numbers
• email_hash - SHA1 email hashes
• phone_hash - SHA1 phone hashes

Response Format

Keys are search criteria, values are wallet objects:

{
    "john@example.com": {
        "id": 887,
        "owner": 5547,
        "account": {
            "number": "EVP..."
        }
    },
    "37066612345": {
        "id": 45,
        "owner": 8879,
        "account": {
            "number": "EVP..."
        }
    }
}

Using Hashes

// Email hash
const emailHash = sha1('email@example.com'.toLowerCase());

// Phone hash  
const phoneHash = sha1('37066612345');

Empty Result

If no wallets found, returns empty object {} (not 404 error).

💳 Card Management

Relate cards to wallets (requires special permissions).

Relate Card

PUT /rest/v1/wallet/:walletId/card

{
    "issuer": "paysera",
    "number": "5487963154"
}

Issuers: vilniecio, paysera

Confirm Card

PUT /rest/v1/wallet/:walletId/confirm

{
    "code": "ABCDEF"
}

User receives confirmation code via SMS/email.

Errors: card_already_assigned, invalid_code, rate_limit_exceeded

---

Common Use Cases

Get User's Main Wallet Balance

GET /rest/v1/wallet/me/balance
Authorization: MAC id="access_token", ...

Check Transaction History

GET /rest/v1/wallet/me/statements?limit=50&currency=EUR,USD
Authorization: MAC id="access_token", ...

Find Wallet by Phone

GET /rest/v1/wallet?phone=37066612345
Authorization: MAC id="client_id", ...

Update Account Description

PUT /rest/v1/wallet/me
Content-Type: application/json

{
    "description": "Business Account"
}

---

Error Handling

Common Errors

Error	Cause	Solution
forbidden	No permission or revoked scope	Check scopes
not_found	Wallet doesn't exist	Verify wallet ID
rate_limit_exceeded	Too many requests	Implement rate limiting
invalid_parameters	Invalid request data	Check parameter format

---

What's Next?

1. User Resource - Manage user information
2. Available Scopes - Review required scopes
3. API Reference - Full endpoint documentation

---

Need Help?

• API Support: tech_support@paysera.com
• Balance Issues: Check scope permissions
• Statement Questions: Review filtering parameters
• Rate Limits: Implement proper rate limiting for PSD2