Using OAuth 2.0

Learn how to implement OAuth 2.0 to get user authorization for accessing their Wallet data.

Overview

The OAuth 2.0 Authorization Framework enables users to authorize your application to access their information without sharing their credentials.

OAuth Implementation:

• Access Tokens: Uses MAC access authentication
• Token Types: Same protocol as client authentication
• Security: Shared secret key used but never sent with request

Available Grant Types:

1. Authorization Code Grant ✅ Recommended

Use for: Web applications, server-side integrations

Flow:

1. Redirect user to Paysera authorization page
2. User authenticates and grants permissions
3. User redirected back with authorization code
4. Exchange code for access token
5. Use token to make API calls

2. Resource Owner Password Credentials Grant ⚠️ Limited

Use for: Mobile and desktop applications (special permission required)

Note: Only allowed for specific clients with special authorization

Recommended Method

Authorization Code Grant is the recommended and most secure method for OAuth implementation.

---

Authorization Code Grant Flow

Follow these steps to implement OAuth using authorization code grant:

Visual Flow Explanation:

1. User initiates - Clicks "Connect with Paysera" on your app
2. Redirect - Your app redirects to Paysera OAuth page
3. User authenticates - Paysera shows login and permission screen
4. User grants access - Approves requested permissions
5. Return with code - Paysera redirects back with authorization code
6. Validate state - Your app verifies CSRF token
7. Exchange code - Backend exchanges code for access token
8. Receive tokens - Get access_token and refresh_token 9-10. Use token - Make authenticated API calls 11-12. Refresh - Optionally refresh expired tokens

---

1️⃣ Step 1: Redirect User to Authorization

Redirect user to Paysera authentication endpoint with required parameters.

Authorization Endpoint

https://www.paysera.com/frontend/oauth

Localized Endpoints

For specific language defaults:

https://www.paysera.com/frontend/en/oauth  (English)
https://www.paysera.com/frontend/lt/oauth  (Lithuanian)
https://www.paysera.com/frontend/ru/oauth  (Russian)

Required Query Parameters

Parameter	Type	Description
response_type	string	Must be code
client_id	string	Your client ID from credentials
redirect_uri	string	URI to redirect after authorization
scope	string	Requested scopes (space-separated)
state	string	CSRF protection token (recommended)

CSRF Protection

Always include the state parameter to prevent cross-site request forgery attacks. Validate it when user returns to your site.

Example Authorization URL

https://www.paysera.com/frontend/oauth?response_type=code&client_id=wkVd93h2uS&redirect_uri=http%3A%2F%2Flocalhost%2Fabc&state=iQZMRnQCtm&scope=email%20balance

---

2️⃣ Step 2: User Authorizes Your Application

After redirecting, the user:

1. Logs into their Paysera account (if not already logged in)
2. Reviews the requested permissions
3. Grants or denies access

---

3️⃣ Step 3: Handle Authorization Response

User is redirected back to your redirect_uri with query parameters.

Success Response

HTTP/1.1 302 Found
Location: http://localhost/abc?code=SplxlOBeZQQYbYS6WxSbIA&state=iQZMRnQCtm

Parameters:

• code - Authorization code (exchange for access token)
• state - Same value you provided (verify it matches)

Error Response

HTTP/1.1 302 Found
Location: http://localhost/abc?error=access_denied&state=iQZMRnQCtm

Error Types:

• invalid_request - Request is malformed
• unauthorized_client - Client not authorized
• access_denied - User denied access
• unsupported_response_type - Invalid response type
• invalid_scope - Invalid scope requested
• server_error - Server error occurred
• temporarily_unavailable - Service temporarily unavailable

Best Practice

Always handle both success and error cases in your redirect handler.

---

4️⃣ Step 4: Exchange Code for Access Token

Make POST request to token endpoint with authorization code.

Token Endpoint

https://wallet.paysera.com/oauth/v1/token

Request Format

Method: POST

Content-Type: application/x-www-form-urlencoded

Authentication: Use your client credentials (MAC or SSL certificate)

Body Parameters:

Parameter	Value
grant_type	authorization_code
code	Authorization code from redirect
redirect_uri	Same URI used in authorization

Example Request

POST /oauth/v1/token HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/x-www-form-urlencoded
Authorization: MAC id="wkVd93h2uS", ts="1343811600", 
    nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", 
    mac="ElTV7TYXQrZrBe0tL6PtqvH6EI15iBSd/JvAkpMoH64=", 
    ext="body_hash=IftzxAtYliLQx46c2JAPidlHKqck0OXD7KmsHNnSptU%3D"

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=http%3A%2F%2Flocalhost%2Fabc

Response Format

{
    "access_token": "SlAV32hkKG",
    "token_type": "mac",
    "expires_in": 3600,
    "mac_key": "adijq39jdlaska9asud",
    "mac_algorithm": "hmac-sha-256",
    "refresh_token": "0UnzbsnOLSkC7ftN"
}

Response Fields:

Field	Description
access_token	Use instead of client_id in API calls
token_type	Always mac
expires_in	Token validity in seconds (typically 3600)
mac_key	Use instead of default mac_key
mac_algorithm	Always hmac-sha-256
refresh_token	Optional - use to renew expired token

Wallet Association

The access token is associated with the specific wallet the user selected during authorization.

---

5️⃣ Step 5: Make API Calls

Use the access token and MAC key to authenticate API requests.

Example API Call

GET /rest/v1/user/me HTTP/1.1
Host: wallet.paysera.com
Authorization: MAC id="SlAV32hkKG", ts="1343825200", 
    nonce="dj83hs9s", 
    mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="

Replace your normal client_id and mac_key with the values from the token response.

---

Advanced Features

Transaction Confirmation with OAuth

Confirming Transaction and Granting Permissions

Combine transaction confirmation with OAuth authorization.

Endpoint

https://www.paysera.com/frontend/transaction/confirm-with-oauth/:transaction_key

Flow:

1. User confirms the transaction
2. Upon success, redirects to OAuth authorization
3. User grants permissions
4. Returns with authorization code

Query Parameters: Same as standard OAuth authorization endpoint

Use Case: Payment confirmation immediately followed by permission granting

Passing Confirmed Contact Information

Ease Registration with Confirmed Contacts

Special Feature

This feature requires special client privileges and is not available by default.

If your client has special privileges, you can provide confirmed contact information to ease user registration.

Create Confirmed Contact Token

POST https://wallet.paysera.com/rest/v1/contact-token

Request Body:

{
    "email": "user@example.com",
    "phone": "37066612345"
}

Response:

{
    "email": "user@example.com",
    "phone": "37066612345",
    "status": "pending",
    "token": "abc123xyz",
    "expires_at": 1234567890
}

Token Validity: 15 minutes

Usage: Include token in OAuth flow to pre-fill and confirm user contacts

Revoking Access Tokens

Delete Access Token

Users can revoke access tokens to remove application permissions.

DELETE https://wallet.paysera.com/oauth/v1/token?access_token=:accessToken

Parameters:

• access_token - The token to revoke (optional if using token for authentication)

Example Request:

DELETE /oauth/v1/token?access_token=SlAV32hkKG HTTP/1.1
Host: wallet.paysera.com
Authorization: MAC id="wkVd93h2uS", ts="1343811600", 
    nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", 
    mac="qtfqgX6EaE0nSHP9fN9ItmTNWqmr1Jkal7IOJbglOOE="

---

Token Management

Token Expiration

Access tokens expire after the time specified in expires_in (typically 1 hour).

Token Refresh

If refresh_token was provided, use it to get new access token without user interaction:

POST /oauth/v1/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=0UnzbsnOLSkC7ftN

Best Practices:

• Store Tokens Securely: Never expose tokens in client-side code
• Handle Expiration: Implement token refresh logic
• Revoke When Done: Delete tokens when no longer needed
• Use HTTPS: Always use secure connections

---

Common OAuth Flows

Web Application Flow

1. User clicks "Connect with Paysera"
2. Redirect to authorization endpoint
3. User authorizes on Paysera
4. Paysera redirects back with code
5. Server exchanges code for token
6. Store token securely server-side
7. Use token for API calls

Mobile Application Flow

1. Open system browser for authorization
2. User authorizes on Paysera
3. Deep link redirects back to app
4. App exchanges code for token
5. Store token in secure storage
6. Use token for API calls

---

Error Handling

Authorization Errors

Always check for error parameter in redirect:

const urlParams = new URLSearchParams(window.location.search);
if (urlParams.has('error')) {
    const error = urlParams.get('error');
    const state = urlParams.get('state');
    // Handle error
}

Token Request Errors

Handle token endpoint errors:

{
    "error": "invalid_grant",
    "error_description": "The authorization code is invalid or expired"
}

---

Security Considerations

Security Requirements

1. Never expose client credentials in client-side code
2. Always validate state parameter to prevent CSRF
3. Use HTTPS for all OAuth communications
4. Implement token refresh before expiration
5. Store tokens securely with encryption
6. Revoke tokens when user logs out or removes app

---

Testing OAuth Flow

Testing in Production:

Production Testing

Wallet API does not have a sandbox environment. All testing must be done in production with small amounts.

Best Practices:

• Start with minimal permissions
• Test with test user accounts
• Use small transaction amounts
• Implement proper error handling

Common Issues:

• Invalid redirect_uri: Must exactly match registered URI
• Invalid state: CSRF token mismatch
• Expired code: Authorization code expired (use within minutes)
• Invalid scope: Requested scope not available

---

What's Next?

1. Explore Available Scopes - Choose permissions
2. Use User Resource - Access user data
3. Use Wallet Resource - Manage wallets

---

Need Help?

• OAuth Issues: tech_support@paysera.com
• Integration Support: Review API Fundamentals
• Scope Questions: Check Available Scopes