Card Deposits

Transfer funds from payment cards to Paysera accounts.

Two-Step Process

Deposits require two steps: Create deposit, then Process deposit.

Create Deposit

Initiate a deposit from a card to an account.

Request

POST /rest/v1/card/{cardId}/deposit
Content-Type: application/json

Required Scope: cards - Required to manage card operations

Request Body

{
    "account_number": "EVP0123456789012",
    "amount": {
        "amount": 1313,
        "currency": "EUR"
    }
}

View Request Parameters

Parameter	Type	Required	Description
account_number	string	✅ Yes	Target account number
amount	object	✅ Yes	Deposit amount

Amount Object

Field	Type	Required	Description
amount	integer	✅ Yes	Amount in cents
currency	string	✅ Yes	Currency code (e.g., EUR)

Response

{
    "id": 26,
    "account_number": "EVP0123456789012",
    "amount": {
        "amount": 1313,
        "currency": "EUR",
        "amount_decimal": "13.13"
    },
    "commission": {
        "amount": 18,
        "currency": "EUR",
        "amount_decimal": "0.18"
    }
}

View Response Fields

Field	Type	Description
id	integer	Deposit ID
account_number	string	Target account
amount	object	Deposit amount
commission	object	Commission charged

---

Process Deposit

Complete the deposit by processing it.

Request

PUT /rest/v1/deposit/{depositId}/process

Parameters

Parameter	Type	Required	Description
depositId	integer	✅ Yes	Deposit ID from create step

Response: Returns the same deposit object with confirmed status.

---

Complete Deposit Flow

async function depositFromCard(cardId, accountNumber, amountEur) {
    try {
        // Step 1: Create deposit
        const deposit = await api.createDeposit(cardId, {
            account_number: accountNumber,
            amount: {
                amount: Math.round(amountEur * 100), // Convert to cents
                currency: 'EUR'
            }
        });
        
        console.log('Deposit Created:');
        console.log(`Amount: €${deposit.amount.amount_decimal}`);
        console.log(`Commission: €${deposit.commission.amount_decimal}`);
        
        const totalCharged = parseFloat(deposit.amount.amount_decimal) + 
                           parseFloat(deposit.commission.amount_decimal);
        console.log(`Total charged from card: €${totalCharged.toFixed(2)}`);
        
        // Step 2: Process deposit
        await api.processDeposit(deposit.id);
        
        console.log('✅ Deposit completed successfully!');
        return deposit;
        
    } catch (error) {
        console.error('Deposit failed:', error.message);
        throw error;
    }
}

// Usage
await depositFromCard(1, 'EVP0123456789012', 50.00);

---

Advanced Topics

Commission Calculation

How It Works

function calculateCommission(amount, commissionRule) {
    const { percent, fix, min, max } = commissionRule;
    
    // Base commission = percentage + fixed
    let commission = (amount * percent / 100) + fix;
    
    // Apply min/max constraints
    if (min && commission < min) {
        commission = min;
    }
    if (max && commission > max) {
        commission = max;
    }
    
    return Math.round(commission); // In cents
}

// Example with 2% + €0.10, min €0.50, max €5.00
const amount = 1000; // €10.00
const rule = {
    percent: 2,
    fix: 10,      // €0.10
    min: 50,      // €0.50
    max: 500      // €5.00
};

const commission = calculateCommission(amount, rule);
// Result: 50 cents (€0.50) - applied minimum

Best Practice 1: Verify Card Status

async function safeDeposit(cardId, depositData) {
    // Check card is ready
    const card = await api.getCard(cardId);
    
    if (card.status !== 'related') {
        throw new Error(`Card is ${card.status}, cannot deposit`);
    }
    
    // Proceed with deposit
    const deposit = await api.createDeposit(cardId, depositData);
    await api.processDeposit(deposit.id);
    
    return deposit;
}

Best Practice 2: Show Total Cost Before Processing

async function depositWithConfirmation(cardId, accountNumber, amount) {
    // Create (but don't process yet)
    const deposit = await api.createDeposit(cardId, {
        account_number: accountNumber,
        amount: { amount: amount * 100, currency: 'EUR' }
    });
    
    // Show user the total
    const total = parseFloat(deposit.amount.amount_decimal) + 
                  parseFloat(deposit.commission.amount_decimal);
    
    console.log(`Amount: €${deposit.amount.amount_decimal}`);
    console.log(`Commission: €${deposit.commission.amount_decimal}`);
    console.log(`Total: €${total.toFixed(2)}`);
    
    // Get confirmation
    const confirmed = await confirm(`Charge €${total.toFixed(2)} from your card?`);
    
    if (confirmed) {
        await api.processDeposit(deposit.id);
        return deposit;
    } else {
        console.log('Deposit cancelled');
        return null;
    }
}

Best Practice 3: Handle Errors

async function depositWithErrorHandling(cardId, accountNumber, amount) {
    try {
        const deposit = await api.createDeposit(cardId, {
            account_number: accountNumber,
            amount: { amount: amount * 100, currency: 'EUR' }
        });
        
        await api.processDeposit(deposit.id);
        return deposit;
        
    } catch (error) {
        switch (error.code) {
            case 'insufficient_funds':
                console.error('Card has insufficient funds');
                break;
            case 'invalid_state':
                console.error('Card is not verified');
                break;
            case 'not_found':
                console.error('Card or account not found');
                break;
            case 'no_rights':
                console.error('No permission to access this account');
                break;
            default:
                console.error('Deposit failed:', error.message);
        }
        throw error;
    }
}

Recurring Deposits

Setup Automatic Deposits

class RecurringDeposit {
    constructor(api, cardId, accountNumber) {
        this.api = api;
        this.cardId = cardId;
        this.accountNumber = accountNumber;
    }
    
    async deposit(amountEur) {
        const deposit = await this.api.createDeposit(this.cardId, {
            account_number: this.accountNumber,
            amount: {
                amount: Math.round(amountEur * 100),
                currency: 'EUR'
            }
        });
        
        await this.api.processDeposit(deposit.id);
        
        console.log(`✅ Deposited €${deposit.amount.amount_decimal}`);
        return deposit;
    }
    
    scheduleWeekly(amountEur, dayOfWeek = 1) {
        // Run every Monday (1) at midnight
        const schedule = `0 0 * * ${dayOfWeek}`;
        
        // Use cron or scheduler
        // cron.schedule(schedule, () => this.deposit(amountEur));
    }
    
    scheduleMonthly(amountEur, dayOfMonth = 1) {
        // Run on 1st of each month
        const schedule = `0 0 ${dayOfMonth} * *`;
        
        // Use cron or scheduler
        // cron.schedule(schedule, () => this.deposit(amountEur));
    }
}

// Usage
const recurring = new RecurringDeposit(api, 1, 'EVP0123456789012');
recurring.scheduleMonthly(100); // €100 on 1st of each month

Common Issues

Issue: "invalid_state" Error

Cause: Card not verified

Solution:

const card = await api.getCard(cardId);
if (card.status !== 'related') {
    throw new Error('Please complete card verification first');
}

Issue: "insufficient_funds"

Cause: Card has insufficient balance

Solution:

// Inform user and suggest lower amount
console.error('Card has insufficient funds');
console.log('Please try a smaller amount or use a different card');

Issue: "no_rights"

Cause: No read access to target account

Solution:

// Verify account access
const accounts = await api.getUserAccounts('me');
const hasAccess = accounts.some(acc => acc.number === accountNumber);

if (!hasAccess) {
    throw new Error('No access to this account');
}

---

Next Steps

• Managing Cards - Create and manage cards
• Overview - Learn about payment cards
• Authentication - Setup OAuth