Payment Samples and Flow Examples

This guide presents practical examples and diagrams showing how to integrate Wallet API payments into your application.

What You'll Learn

• How to make one-time payments
• How to use allowances for recurring payments
• Complete integration flows with code examples

Payment Integration Flows

One-Time Payment Flow

This is the most common payment scenario - user makes a single payment that requires their confirmation.

Use Cases:

• 🛒 E-commerce checkout
• 💰 Single service purchases
• 🎫 Event ticket sales
• 📦 One-time product orders

---

Allowance Payment Flow

Create an allowance once, then make background payments without user interaction.

Use Cases:

• 📅 Subscription billing
• 🔄 Recurring service charges
• 📱 Usage-based billing
• 🎮 In-app microtransactions

---

Example 1: One-Time Payment

Using PHP Library

Using PHP Library

The easiest way to integrate - use our official PHP library.

Step 1: Install Library

composer require paysera/lib-wallet-php-client

Or download from GitHub.

Step 2: Create Payment Script

payment.php

<?php

require_once 'vendor/autoload.php';

use Paysera\WalletApi\WalletApi;
use Paysera\WalletApi\Entity\Money;
use Paysera\WalletApi\Entity\Item;
use Paysera\WalletApi\Entity\Payment;
use Paysera\WalletApi\Entity\Transaction;
use Paysera\WalletApi\Util\Router;

session_start();

// Your Paysera credentials
$clientId = 'your_client_id';
$secret = 'your_mac_key';

// Initialize API for production
$api = new WalletApi(
    $clientId, 
    $secret, 
    Router::createForProduction()
);

try {
    if (!isset($_SESSION['transactionKey'])) {
        // Create payment
        $price = Money::create()
            ->setAmountInCents(1299) // 12.99 EUR
            ->setCurrency('EUR');

        $item = Item::create()
            ->setTitle('Premium Subscription')
            ->setDescription('1 month access')
            ->setImageUri('https://example.com/product.jpg')
            ->setPrice($price)
            ->setQuantity(1);

        $payment = Payment::create()
            ->addItem($item)
            ->setDescription('Premium Subscription Payment');

        $transaction = Transaction::create()
            ->addPayment($payment)
            ->setRedirectUri('https://yoursite.com/payment-return');

        // Create transaction in Paysera
        $created = $api->walletClient()->createTransaction($transaction);
        $_SESSION['transactionKey'] = $created->getKey();

        // Redirect user to confirmation
        header('Location: ' . $api->router()
            ->getTransactionConfirmationUri($created->getKey()));
        exit;
    }

    // User returned after confirmation
    if (isset($_SESSION['transactionKey'])) {
        $transaction = $api->walletClient()
            ->getTransaction($_SESSION['transactionKey']);

        if ($transaction->getStatus() === 'reserved') {
            // Confirm the transaction
            $api->walletClient()->confirmTransaction($transaction->getKey());
            
            echo "Payment successful!";

            // Implement your business logic here:
            // - Update order status in your database
            // - Send confirmation email to customer
            // - Trigger fulfillment process
            // Example: $order->setStatus('paid')->save();
        }

        unset($_SESSION['transactionKey']);
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

Key Points

✅ Session management - Store transaction key in session
✅ Error handling - Always wrap in try-catch
✅ Status check - Verify reserved status before confirming
✅ Cleanup - Unset session variable after processing

Direct API Calls

Using Direct API Calls

For non-PHP applications or when you need more control.

Step 1: Create Transaction

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

{
  "payments": [{
    "description": "Payment for order #1234",
    "price": 1299,
    "currency": "EUR",
    "parameters": {
      "orderid": "1234"
    }
  }],
  "redirect_uri": "https://yoursite.com/payment-return"
}

Response:

{
  "transaction_key": "pDAlAZ3z",
  "status": "new",
  "payments": [{
    "id": 2988,
    "status": "new",
    "price": 1299,
    "currency": "EUR"
  }]
}

Step 2: Redirect User

Redirect to confirmation page:

https://www.paysera.com/frontend/en/wallet/confirm/pDAlAZ3z

Step 3: Confirm Transaction

After user accepts and returns to your site:

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

Response:

{
  "transaction_key": "pDAlAZ3z",
  "status": "confirmed",
  "payments": [{
    "id": 2988,
    "status": "confirmed",
    "price": 1299
  }]
}

---

Example 2: Allowance for Recurring Payments

Using PHP Library

Phase 1: Create Allowance

Create an allowance that user accepts once:

create-allowance.php

<?php

require_once 'vendor/autoload.php';

use Paysera\WalletApi\WalletApi;
use Paysera\WalletApi\Entity\Money;
use Paysera\WalletApi\Entity\Allowance;
use Paysera\WalletApi\Entity\Transaction;

session_start();

$api = new WalletApi($clientId, $secret, Router::createForProduction());

try {
    if (!isset($_SESSION['allowanceKey'])) {
        // Create allowance - max 5 EUR for 7 days
        $maxPrice = Money::create()
            ->setAmountInCents(500)
            ->setCurrency('EUR');

        $allowance = Allowance::create()
            ->setDescription('Weekly subscription (5 EUR/week)')
            ->setMaxPrice($maxPrice)
            ->setValidFor(604800); // 7 days in seconds

        $transaction = Transaction::create()
            ->setAllowance($allowance)
            ->setRedirectUri('https://yoursite.com/allowance-return');

        $created = $api->walletClient()->createTransaction($transaction);
        $_SESSION['allowanceKey'] = $created->getKey();

        // Redirect to confirmation
        header('Location: ' . $api->router()
            ->getTransactionConfirmationUri($created->getKey()));
        exit;
    }

    // User returned after accepting
    if (isset($_SESSION['allowanceKey'])) {
        $transaction = $api->walletClient()
            ->getTransaction($_SESSION['allowanceKey']);

        if ($transaction->getStatus() === 'reserved') {
            $api->walletClient()->confirmTransaction($transaction->getKey());
            
            // Store allowance info for future use
            $_SESSION['activeAllowance'] = [
                'id' => $transaction->getAllowance()->getId(),
                'wallet' => $transaction->getWallet()
            ];
            
            echo "Allowance created successfully!";
        }

        unset($_SESSION['allowanceKey']);
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

Phase 2: Make Background Payments

Now you can charge automatically without user interaction:

charge-with-allowance.php

<?php

require_once 'vendor/autoload.php';

use Paysera\WalletApi\WalletApi;
use Paysera\WalletApi\Entity\Money;
use Paysera\WalletApi\Entity\Payment;
use Paysera\WalletApi\Entity\Transaction;

session_start();

$api = new WalletApi($clientId, $secret, Router::createForProduction());

try {
    // Get stored allowance info
    $allowanceInfo = $_SESSION['activeAllowance'];
    
    // Create payment
    $price = Money::create()
        ->setAmountInCents(300) // 3 EUR (within 5 EUR limit)
        ->setCurrency('EUR');

    $payment = Payment::create()
        ->setPrice($price)
        ->setDescription('Weekly service charge');

    // Get the allowance transaction
    $allowanceTx = $api->walletClient()
        ->getTransaction($allowanceInfo['transaction_key']);

    // Create new transaction with allowance
    $transaction = Transaction::create()
        ->addPayment($payment)
        ->setAllowance($allowanceTx->getAllowance());

    $created = $api->walletClient()->createTransaction($transaction);

    // Accept using allowance (NO user interaction needed!)
    $api->walletClient()->acceptTransactionUsingAllowance(
        $created->getKey(),
        $allowanceInfo['wallet']
    );

    // Confirm immediately
    $api->walletClient()->confirmTransaction($created->getKey());

    echo "Payment charged successfully via allowance!";
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
    // Allowance might be expired or insufficient balance
}

Direct API Calls

Phase 1: Create Allowance

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

{
  "description": "Weekly subscription (5 EUR/week)",
  "currency": "EUR",
  "max_price": 500,
  "valid": {
    "for": 604800
  }
}

Response:

{
  "id": 2987,
  "transaction_key": "pDAlAZ3z",
  "status": "new",
  "max_price": 500,
  "currency": "EUR"
}

Redirect user to accept, then confirm transaction.

Phase 2: Background Payment

POST /rest/v1/transaction HTTP/1.1
Content-Type: application/json

{
  "payments": [{
    "price": 300,
    "currency": "EUR",
    "description": "Weekly charge"
  }],
  "allowance": {
    "id": 2987,
    "optional": false
  }
}

Then reserve using allowance:

PUT /rest/v1/transaction/{key}/reserve/{wallet_id} HTTP/1.1

And confirm:

PUT /rest/v1/transaction/{key}/confirm HTTP/1.1

---

Additional Examples

🛒 Example 3: Payment with Items

Detailed itemized payment (like shopping cart):

$items = [];

// Add multiple items
$items[] = Item::create()
    ->setTitle('Product A')
    ->setPrice(Money::create()->setAmountInCents(999)->setCurrency('EUR'))
    ->setQuantity(2);

$items[] = Item::create()
    ->setTitle('Product B')
    ->setPrice(Money::create()->setAmountInCents(1499)->setCurrency('EUR'))
    ->setQuantity(1);

$payment = Payment::create()
    ->setDescription('Order #1234');

foreach ($items as $item) {
    $payment->addItem($item);
}

// Total: 2×9.99 + 1×14.99 = 34.97 EUR

💵 Example 4: Payment with Commission

Add commission/fee to payment:

$payment = Payment::create()
    ->setPrice(Money::create()->setAmountInCents(1000)->setCurrency('EUR'))
    ->setDescription('Service payment');

// Add 10% commission
$commission = Commission::create()
    ->setOutCommission(Money::create()->setAmountInCents(100)->setCurrency('EUR'));

$payment->setCommission($commission);

---

Testing Your Integration

Production Testing

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

Testing Strategy:

• Start with small amounts (1-5 EUR)
• Use test user accounts
• Test all payment scenarios thoroughly
• Monitor real transactions carefully

---

Common Patterns

Auto-Confirm Pattern

For trusted scenarios (donations, transfers):

$transaction = Transaction::create()
    ->addPayment($payment)
    ->setAutoConfirm(true); // Auto-confirms after acceptance

Use Carefully

Only use auto-confirm when you don't provide services that might fail.

Reserved Payment Pattern

For delayed charges (hotel bookings):

$payment = Payment::create()
    ->setPrice($price)
    ->setFreezeUntil(strtotime('+7 days')); // Hold for 7 days

Later, finalize or cancel:

// Charge the held amount
$api->walletClient()->finalizePayment($paymentId);

// Or cancel and release funds
$api->walletClient()->cancelPayment($paymentId);

---

Next Steps

Now that you understand the payment flows:

• Payment Resource - Detailed API reference (coming soon)
• Authorising Transactions - All acceptance methods (coming soon)
• Callbacks - Handle payment notifications (coming soon)
• Transaction Resource - Complete transaction API (coming soon)

---

Need Help?

• Library Issues: GitHub Issues
• API Support: tech_support@paysera.com
• Documentation: Wallet API Overview