Skip to main content

Cash-out with Code

Perform secure cash-out to customers using their generated reservation code from Paysera app.

Use Case Overview​

Customer generates a reservation code in Paysera mobile app, you scan it and process cash-out at your location.

Implementation Steps​

1. Customer Generates Code

Customer opens Paysera app and generates a reservation code for cash withdrawal.

2. Create Transaction
POST /rest/v1/transaction HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json
Authorization: MAC id="...", ...

{
  "payments": [
    {
      "description": "Cash withdrawal",
      "price": 5000,
      "currency": "EUR"
    }
  ]
}

Response:

{
  "transaction_key": "ATaNL6X6CivO2Ou0FMPt",
  "status": "new",
  "payments": [
    {
      "id": 186975531,
      "price": 5000,
      "currency": "EUR",
      "price_decimal": "50.00"
    }
  ]
}
3. Reserve with Code

Scan customer's reservation code and reserve the money:

PUT /rest/v1/transaction/ATaNL6X6CivO2Ou0FMPt/reserve HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json
Authorization: MAC id="...", ...

{
  "code": "0155567464130298871198969060"
}

Response:

{
  "transaction_key": "ATaNL6X6CivO2Ou0FMPt",
  "status": "reserved",
  "type": "reservation_code",
  "wallet": 14471,
  "payments": [
    {
      "id": 186975531,
      "status": "reserved",
      "price_decimal": "50.00"
    }
  ]
}
4. Confirm Transaction

After verifying customer identity, confirm the transaction:

PUT /rest/v1/transaction/ATaNL6X6CivO2Ou0FMPt/confirm HTTP/1.1
Host: wallet.paysera.com
Authorization: MAC id="...", ...

Response:

{
  "transaction_key": "ATaNL6X6CivO2Ou0FMPt",
  "status": "confirmed",
  "confirmed_at": 1585146195,
  "payments": [
    {
      "id": 186975531,
      "status": "confirmed",
      "price_decimal": "50.00",
      "confirmed_at": 1585146195
    }
  ]
}

5. Give Cash to Customer

Once confirmed, give the cash to customer.

Complete Example​

async function processCashOut(reservationCode, amount) {
    // 1. Create transaction
    const transaction = await api.createTransaction({
        payments: [{
            description: 'Cash withdrawal',
            price: amount * 100,
            currency: 'EUR'
        }]
    });
    
    console.log(`Transaction created: ${transaction.transaction_key}`);
    
    // 2. Reserve money with code
    const reserved = await api.reserveTransaction(
        transaction.transaction_key,
        { code: reservationCode }
    );
    
    if (reserved.status !== 'reserved') {
        throw new Error('Failed to reserve money');
    }
    
    console.log('Money reserved successfully');
    
    // 3. Confirm transaction
    const confirmed = await api.confirmTransaction(
        transaction.transaction_key
    );
    
    if (confirmed.status !== 'confirmed') {
        throw new Error('Failed to confirm transaction');
    }
    
    console.log('Transaction confirmed. Give cash to customer.');
    
    return confirmed;
}

// Usage
const code = scanReservationCode();
await processCashOut(code, 50.00);

Advanced Topics​

Error Handling

Invalid Reservation Code

{
  "error": "invalid_request",
  "error_description": "Invalid reservation code"
}

Solution: Ask customer to generate a new code.

Insufficient Funds

{
  "error": "insufficient_funds",
  "error_description": "Not enough money in wallet"
}

Solution: Customer needs to add funds or reduce amount.

Expired Code

{
  "error": "code_expired",
  "error_description": "Reservation code has expired"
}

Solution: Customer generates new code.

Best Practices

1. Verify Amount

function verifyAmount(scannedAmount, requestedAmount) {
    if (scannedAmount !== requestedAmount) {
        throw new Error('Amount mismatch');
    }
}

2. Set Transaction Timeout

const transaction = await api.createTransaction({
    payments: [...],
    reserve: {
        for: 300  // 5 minutes
    }
});

3. Handle Cancellation

async function cancelCashOut(transactionKey) {
    await api.cancelTransaction(transactionKey);
    console.log('Cash-out cancelled');
}
Security Considerations

Do:

  • ✅ Verify customer identity before giving cash
  • ✅ Use short reservation timeouts (5-10 minutes)
  • ✅ Log all transactions for audit trail
  • ✅ Implement amount limits per transaction
  • ✅ Require supervisor approval for large amounts

Don't:

  • ❌ Don't store reservation codes
  • ❌ Don't allow unlimited retry attempts
Testing
Production Testing

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

Test Scenarios:

  • ✅ Successful cash-out
  • ✅ Invalid code
  • ✅ Insufficient funds
  • ✅ Expired code
  • ✅ Cancelled transaction
  • ✅ Network timeout