Upload Funds to Wallet

Allow users to add money to their Paysera wallet via redirect to Paysera's hosted upload page.

Use Case Overview

Redirect users to Paysera's hosted upload page where they can:

Select amount to deposit
Choose payment method (bank transfer, card, etc.)
Complete the deposit
Return to your application

Hosted Solution

This uses Paysera's hosted page - no API integration needed for the upload itself.

Basic Implementation

function redirectToUploadFunds(clientId, walletId, redirectUri) {
    const params = new URLSearchParams({
        client_id: clientId,
        wallet_id: walletId,
        redirect_uri: redirectUri
    });
    
    const url = `https://www.paysera.com/frontend/en/wallet/upload-funds?${params}`;
    window.location.href = url;
}

// Usage
redirectToUploadFunds('12345678', '14471', 'https://yoursite.com/callback');

URL Parameters

Parameter	Type	Required	Description
`client_id`	string	Yes (if using any params)	Your API client ID
`wallet_id`	integer	No	Expected wallet ID
`redirect_uri`	string	No	Return URL after completion

Example URL:

https://www.paysera.com/frontend/en/wallet/upload-funds?client_id=12345678&wallet_id=14471&redirect_uri=https%3A%2F%2Fyoursite.com%2Fcallback

Handling Response

Status Codes:

Status	Description
`success`	Funds uploaded successfully
`reject`	User cancelled upload
`error`	Error occurred

Parse Response:

function handleUploadCallback() {
    const params = new URLSearchParams(window.location.search);
    const status = params.get('status');
    
    switch (status) {
        case 'success':
            showMessage('✅ Funds uploaded successfully!');
            updateUserBalance();
            break;
        case 'reject':
            showMessage('❌ Upload cancelled');
            break;
        case 'error':
            showMessage('⚠️ An error occurred');
            break;
    }
}

Integration Methods

Method 1: Full Page Redirect

function uploadFundsFullPage() {
    window.location.href = buildUploadUrl({
        client_id: YOUR_CLIENT_ID,
        wallet_id: userWalletId,
        redirect_uri: 'https://yoursite.com/callback'
    });
}

Method 2: Popup Window

function uploadFundsPopup() {
    const url = buildUploadUrl({
        client_id: YOUR_CLIENT_ID,
        wallet_id: userWalletId,
        redirect_uri: 'https://yoursite.com/callback'
    });
    
    const popup = window.open(url, 'payseraUpload', 'width=600,height=700');
    
    window.addEventListener('message', (event) => {
        if (event.origin === 'https://www.paysera.com') {
            handleUploadResult(event.data);
            popup.close();
        }
    });
}

Method 3: iFrame

<iframe 
    id="uploadFrame"
    src="https://www.paysera.com/frontend/en/wallet/upload-funds?client_id=12345678"
    width="600"
    height="700"
    frameborder="0">
</iframe>

window.addEventListener('message', (event) => {
    if (event.origin === 'https://www.paysera.com') {
        const { status } = event.data;
        handleUploadResult(status);
    }
});

Complete Example

class WalletUploadManager {
    constructor(clientId) {
        this.clientId = clientId;
        this.baseUrl = 'https://www.paysera.com/frontend/en/wallet/upload-funds';
    }
    
    buildUrl(options = {}) {
        const params = new URLSearchParams({
            client_id: this.clientId,
            ...options
        });
        return `${this.baseUrl}?${params}`;
    }
    
    redirectToUpload(walletId, returnUrl) {
        const url = this.buildUrl({
            wallet_id: walletId,
            redirect_uri: returnUrl
        });
        window.location.href = url;
    }
    
    openInPopup(walletId) {
        return new Promise((resolve, reject) => {
            const url = this.buildUrl({
                wallet_id: walletId,
                redirect_uri: window.location.origin + '/upload-callback'
            });
            
            const popup = window.open(url, 'upload', 'width=600,height=700');
            
            window.addEventListener('message', (event) => {
                if (event.origin === 'https://www.paysera.com') {
                    popup.close();
                    
                    if (event.data.status === 'success') {
                        resolve(event.data);
                    } else {
                        reject(new Error(event.data.status));
                    }
                }
            });
        });
    }
    
    handleCallback() {
        const params = new URLSearchParams(window.location.search);
        const status = params.get('status');
        
        return {
            success: status === 'success',
            cancelled: status === 'reject',
            error: status === 'error',
            status
        };
    }
}

// Usage
const uploadManager = new WalletUploadManager('12345678');

// Redirect
uploadManager.redirectToUpload(userWalletId, '/dashboard');

// Popup
try {
    await uploadManager.openInPopup(userWalletId);
    refreshBalance();
} catch (error) {
    console.error('Upload failed:', error);
}

Advanced Topics

Language-Specific URLs

const UPLOAD_URLS = {
    en: 'https://www.paysera.com/frontend/en/wallet/upload-funds',
    lt: 'https://www.paysera.com/frontend/wallet/upload-funds',
    ru: 'https://www.paysera.com/frontend/ru/wallet/upload-funds'
};

function getUploadUrl(language = 'en') {
    return UPLOAD_URLS[language] || UPLOAD_URLS.en;
}

Using JavaScript SDK

<script src="https://cdn.paysera.com/wallet/js/wallet-sdk.js"></script>

const paysera = new PayseraWallet({
    client_id: '12345678'
});

paysera.uploadFunds({
    wallet_id: userWalletId,
    onSuccess: () => {
        console.log('Upload successful');
        refreshBalance();
    },
    onCancel: () => {
        console.log('Upload cancelled');
    },
    onError: (error) => {
        console.error('Upload error:', error);
    }
});

Wallet ID Validation

function validateWalletId(providedId, expectedId) {
    if (providedId !== expectedId) {
        console.warn('Wallet ID mismatch');
        return false;
    }
    return true;
}

Wallet ID Mismatch

If user uses different wallet than specified in wallet_id, Paysera will show a notification but still allow the upload.

Best Practices

1. Always Provide Redirect URI

// ✅ Good
const url = buildUploadUrl({
    client_id: CLIENT_ID,
    wallet_id: walletId,
    redirect_uri: 'https://yoursite.com/callback'
});

// ❌ Bad - no way to handle result
const url = buildUploadUrl({
    client_id: CLIENT_ID,
    wallet_id: walletId
});

2. URL Encode Parameters

function buildUploadUrl(params) {
    const encoded = Object.entries(params).map(([key, value]) => 
        `${key}=${encodeURIComponent(value)}`
    ).join('&');
    
    return `${baseUrl}?${encoded}`;
}

3. Handle All Status Cases

function handleResult(status) {
    switch (status) {
        case 'success':
            // Update balance, show success message
            break;
        case 'reject':
            // User cancelled, no action needed
            break;
        case 'error':
            // Show error, maybe retry option
            break;
        default:
            console.error('Unknown status:', status);
    }
}

Security Considerations

Do:

✅ Always use HTTPS for redirect_uri
✅ Validate status parameter on callback
✅ Don't trust amount from URL params
✅ Fetch actual balance from API after success

Don't:

❌ Don't pass sensitive data in URL
❌ Don't skip validation on callback

Troubleshooting

Popup Blocked

// Solution: Open on user action
button.addEventListener('click', () => {
    window.open(uploadUrl, 'upload', 'width=600,height=700');
});

// ❌ This will be blocked
setTimeout(() => {
    window.open(uploadUrl); // Popup blocker!
}, 1000);

iFrame Not Loading

// Ensure client_id is provided
const url = buildUrl({
    client_id: CLIENT_ID,  // Required for iframe!
    wallet_id: walletId
});

Testing

Production Testing

Wallet API does not have a sandbox environment. Test with real transactions and small amounts.

Test Flow:

Redirect to upload page with your client_id
Select amount (use small test amounts)
Choose payment method
Complete payment
Verify redirect back to your site
Check status parameter
Fetch balance to confirm

Authentication - Client credentials
User Information - Get wallet balance

Use Case Overview​

Basic Implementation​

URL Parameters​

Handling Response​

Integration Methods​

Complete Example​

Advanced Topics​

Related Documentation​