Skip to main content

Payments Overview

The Wallet API enables you to initiate and control payment transactions between Paysera accounts. This powerful feature allows you to collect payments, send money to users, and coordinate complex payment flows.

Authentication

When making payments, default client credentials are sufficient - no OAuth integration is required.

Overview​

The Payments system in Wallet API consists of several interconnected resources that work together to create secure and flexible payment flows.

Core Resources​

Wallet - Always related to a specific user and account. Each user can have multiple wallets with different limits and options. Wallets can be linked to cards or other identifiers.

Payment - Transfer of funds from one wallet to another. Can be itemized or contain only price information for display purposes.

Transaction - Groups one or more payments and optionally an allowance. The entire transaction is either accepted or rejected as a whole.

Allowance - Enables charging a wallet without user interaction, as long as payments don't exceed predefined limits.

Commission - Fee or additional charge associated with a payment.

Transaction Lifecycle​

Every transaction follows a defined flow from creation to completion:

1️⃣ Created​

Transaction is created by your client. Information is saved in Paysera system, but no money is transferred or reserved.

2️⃣ Accepted​

User accepts the transaction and relates it to a specific wallet. This can be done by:

  • Redirecting user to confirmation page
  • Providing user's PIN via API
  • Using a pre-approved allowance (no user interaction needed)

Result: Funds are reserved in the payer's account, but not yet visible to beneficiary.

3️⃣ Confirmed or Revoked​

Your client must confirm or revoke the transaction. This step ensures:

  • ✅ Your system is still operational
  • ✅ Services can still be provided
  • ✅ Payment amounts can be adjusted if needed

Auto-confirm: Set auto_confirm: true when creating transaction to skip manual confirmation (use carefully).

Result: Payments become visible to beneficiary. If freezeUntil is set, funds remain frozen until that time.

4️⃣ Finalized or Cancelled (Optional)​

For payments with freezeUntil, you can:

  • Finalize payment (optionally reducing the amount)
  • Cancel payment (full refund)

Result: Payment is completed or fully cancelled.

Transaction Status Flow​

Key Statuses​

StatusDescriptionCan transition to
newJust created, awaiting acceptancewaiting, failed
waitingAccepted, funds reservedreserved, failed
reservedConfirmed, visible to beneficiarydone, canceled
done✅ Payment completed-
canceled❌ Payment cancelled/revoked-
failed❌ Payment failed-

Payment Scenarios​

💡 View Common Payment Scenarios

Scenario 1: Simple Payment

Use case: Single payment, immediate confirmation

// 1. Create transaction with payment
POST /rest/v1/transaction

// 2. User accepts (redirect or PIN)
PUT /rest/v1/transaction/{id}/accept

// 3. Confirm transaction
PUT /rest/v1/transaction/{id}/confirm

Scenario 2: Payment with Allowance

Use case: Recurring payments, no user interaction

// 1. Create allowance (user accepts once)
POST /rest/v1/allowance

// 2. Create transaction with allowance
POST /rest/v1/transaction
{
  "allowance_id": 123
}

// 3. Confirm (or auto-confirm)
PUT /rest/v1/transaction/{id}/confirm

Scenario 3: Reserved Payment

Use case: Reserve now, charge later (e.g., hotel booking)

// 1. Create with freezeUntil
POST /rest/v1/transaction
{
  "payments": [{
    "freeze_until": "2024-12-31"
  }]
}

// 2. Accept & Confirm
// Funds frozen until date

// 3. Finalize when ready
PUT /rest/v1/payment/{id}/finalize

Getting Started with Payments​

Ready to integrate payments into your application?

Learn the Fundamentals

  1. Samples & Examples - View real-world payment scenarios (see Payment Basics section)
  2. Payment Concepts - Understand wallets, payments, transactions, and allowances (coming soon)
  3. Transaction Flow - Learn the complete payment lifecycle (coming soon)

Explore Resources

  1. Payment Resource - Create and manage payments (coming soon)
  2. Transaction Resource - Control transaction lifecycle (coming soon)
  3. Allowance Resource - Set up recurring payments (coming soon)
  4. Commission Resource - Handle fees and charges (coming soon)
  5. Inquiries - Request additional information (coming soon)

Integrate into Your App

  1. Authorising Transactions - Accept payments securely (coming soon)
  2. Callbacks - Handle payment notifications (coming soon)
  3. Transaction Requests - Request payments from users (coming soon)
  4. Reservation Codes - Generate payment codes (coming soon)

Common Use Cases​

🎯 View Common Use Cases

💳 E-commerce Checkout

Accept payments for online purchases with immediate confirmation.

🔄 Subscription Billing

Use allowances for recurring monthly subscriptions.

🏨 Hotel Reservations

Reserve funds at booking, charge upon check-out using freezeUntil.

👥 Peer-to-Peer Transfers

Enable users to send money to each other using transaction requests.

💰 Split Payments

Create transactions with multiple payments to split costs.

Need Help?​

What's Next?​

Choose your path based on your needs:

  • New to Payments? → Check Payment Basics section in sidebar
  • Ready to Code? → Explore Payment concepts and resources (coming soon)
  • Need Help? → Contact tech_support@paysera.com