Available Scopes

Scopes define what information your application can access and what actions it can perform on behalf of the user.

Understanding Scopes

Scopes are passed when requesting an access token and determine API permissions.

Scope Types

Offline Scopes (*_offline)

Purpose: Access user information permanently without requiring access token

How it works:

• Add _offline suffix to any scope (e.g., balance_offline)
• User confirms scope during OAuth authorization
• After confirmation, you can access information using default credentials
• No need to use access token for subsequent requests

Example: email_offline, balance_offline, statements_offline

Benefits:

• Get user ID with access token
• Access information anytime with default credentials
• No token expiration concerns

Can Be Revoked

Users can revoke offline scopes in their Paysera account. Always handle forbidden errors.

Availability

Offline scopes only available with authorization code grant.

---

Optional Scopes (*_optional)

Purpose: Request access without forcing immediate user action

How it works:

• Add _optional suffix (e.g., phone_optional)
• Can be combined with offline: phone_offline_optional
• Information accessible only after user meets scope conditions
• Returns not_found error until conditions met

Example: email_optional, phone_offline_optional

Use case: Gradually request permissions as needed without blocking user flow

Combining Suffixes

When combining offline and optional: scope_offline_optional (offline first, then optional)

---

Extended Scopes

Purpose: Higher-risk actions requiring special authorization

How it works:

• Cannot be requested during token request
• Must be attached during token refresh
• Requires code parameter (SMS confirmation code)
• User receives SMS for verification

Example: convert_currency

Process:

1. Request token without extended scope
2. User receives SMS with code
3. Refresh token with code parameter
4. Extended scope added to token

---

Complete Scope List

📋 User Information Scopes (10 scopes)

Scope	Description	Offline	Optional
email	Get user's confirmed email address	✅	✅
phone	Get user's confirmed phone number	✅	✅
address	Get user's address	✅	✅
dob	Get user's date of birth	✅	✅
gender	Get user's gender	✅	✅
full_name	Get confirmed name and surname (requires identification)	✅	✅
identification_level	Get user's identification level	✅	-
identity	Get confirmed name, surname, nationality, and ID code (requires identification)	✅	✅
identification_data	Get identification information (personal code, documents)	✅	-
user_info	Get basic user information (locale, preferences)	✅	-

💰 Wallet & Transaction Scopes (5 scopes)

Scope	Description	Offline	Optional
balance	Get balance of user's wallet	✅	-
check_has_sufficient_balance	Check if user has sufficient funds	-	-
statements	Get account statements and transaction history	✅	-
wallet_list	Get list of all available wallets for user	✅	-
favourites	Get most common payment beneficiaries	✅	-

💸 Payment & Transfer Scopes (4 scopes)

Scope	Description	Offline	Optional
incoming_payments	Access incoming pending payments and provide passwords	✅	-
outgoing_payments	Access outgoing pending payments with passwords	✅	-
initiate_transfers	Initiate transfers on user's behalf	-	-
convert_currency	Make currency conversions (Extended scope)	-	-

🔧 Project & Service Scopes (3 scopes)

Scope	Description	Offline	Optional
projects	Access and manage user's administered projects	✅	-
services	Get list of enabled services or enable service for user	✅	-
cards	Manage user's cards (create, edit, delete, link with accounts)	✅	-

➕ Additional Scopes (7 scopes)

Scope	Description	Offline	Optional
sent_transaction_requests	Access initiated transaction requests	✅	-
received_transaction_requests	Access received transaction requests	✅	-
user_position	Provide user's current position	✅	-
avatar	Provide, change, and delete user's avatar	✅	-
manage_account	Change and delete account descriptions	✅	-
phone_confirmation	Send transaction confirmation FLASH SMS	✅	-
pep	Get user's list of politically exposed persons	-	✅

---

Scope Examples

→ See how to use scopes in OAuth: Implement OAuth

Basic User Information

Request email and phone:

scope=email phone

Offline Access

Request permanent access to balance:

scope=balance_offline

→ Learn more: Understanding Scope Types

Optional Information

Request email but don't require immediate confirmation:

scope=email_optional

Combined

Request offline optional phone:

scope=phone_offline_optional

Multiple Scopes

Request several permissions:

scope=email balance statements wallet_list

→ See API usage: User Resource | Wallet Resource

---

Choosing Scopes

→ Quick reference: Complete Scope List

Considerations:

1. Minimal Permissions: Only request scopes you actually need
2. User Experience: More scopes may reduce authorization rate
3. Offline vs Regular: Use offline for long-term access
4. Optional Strategy: Use for progressive permission requests

💡 Common Scope Combinations

Basic Profile Access

email phone user_info

Payment Application

balance statements incoming_payments outgoing_payments

Full User Profile

email phone address identity identification_level

Financial Dashboard

balance_offline statements_offline wallet_list_offline

---

Scope Behavior

User Must Meet Requirements

Some scopes require user action before granting:

Scope	Requirement
phone	User must add and validate phone number
address	User must input address
full_name	User must perform identification
identity	User must perform identification
phone_confirmation	User must add and validate phone number

If requirements not met:

• Regular scope: User asked to complete during OAuth flow
• Optional scope: Returns not_found until completed

---

Testing Scopes

Production Testing

Wallet API does not have a sandbox environment. Test in production with small amounts and test accounts.

Testing Steps:

1. Create test user accounts
2. Request scopes during OAuth (OAuth Guide)
3. Verify data access with access token
4. Test offline scopes with default credentials

Verification:

Check scope access:

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

Response will only include fields for granted scopes.

→ API Authentication: Authentication Guide

---

Scope Errors

⚠️ Common Errors & Solutions

invalid_scope

Cause: Requested scope doesn't exist or not available for your client

Solution: Check scope spelling and availability

---

forbidden

Cause:

• Offline scope was revoked by user
• Client doesn't have permission for scope

Solution: Re-request authorization or check client permissions

---

not_found

Cause: Optional scope not yet fulfilled by user

Solution: Wait for user to complete requirements or handle gracefully

---

What's Next?

1. Implement OAuth - Set up OAuth flow with chosen scopes
2. Use User Resource - Access user data
3. Use Wallet Resource - Access wallet information

---

Need Help?

• Scope Questions: tech_support@paysera.com
• Permission Denied: Check client configuration
• Integration Support: Review API Documentation