Transaction Resource

The Transaction Resource represents a container for one or more payments and optionally an allowance. It manages the complete payment lifecycle from creation to completion.

Quick Start

New to transactions? Start with Transaction Flow to understand the lifecycle.

Transaction Object

Structure

{
  "transaction_key": "pDAlAZ3z",
  "created_at": 1698675600,
  "status": "confirmed",
  "type": "page",
  "wallet": 14471,
  "confirmed_at": 1698675680,
  "redirect_uri": "https://yoursite.com/payment-return",
  "callback_uri": "https://yoursite.com/payment-callback",
  "auto_confirm": false,
  "use_allowance": true,
  "payments": [
    {
      "id": 2988,
      "price": 2999,
      "currency": "EUR",
      "status": "done"
    }
  ]
}

View Fields Reference

Field	Type	Description
`transaction_key`	string	Unique transaction identifier
`created_at`	timestamp	When transaction was created
`status`	string	Transaction status
`type`	string	Transaction type
`wallet`	integer	Payer's wallet ID (after acceptance)
`confirmed_at`	timestamp	When transaction was confirmed
`project_id`	integer	Your project ID
`manager_id`	integer	Manager user ID (if applicable)
`reserve`	object	Reservation settings
`redirect_uri`	string	Where to redirect user after payment
`callback_uri`	string	Where to send payment notifications
`auto_confirm`	boolean	Auto-confirm after acceptance
`use_allowance`	boolean	Whether allowance is being used
`suggest_allowance`	boolean	Suggest creating allowance to user
`password_request`	object	Password requirement settings
`payments`	array	Array of payment objects
`allowance`	object	Allowance object (if used)

Creating a Transaction

View Creation Examples

Basic Transaction

POST /rest/v1/transaction

{
  "payments": [{
    "description": "Order #1234",
    "price": 2999,
    "currency": "EUR"
  }],
  "redirect_uri": "https://yoursite.com/payment-return"
}

Response:

{
  "transaction_key": "pDAlAZ3z",
  "status": "new",
  "payments": [{
    "id": 2988,
    "price": 2999,
    "status": "new"
  }]
}

Transaction with Multiple Payments

{
  "payments": [
    {
      "description": "Payment to Seller A",
      "price": 5000,
      "currency": "EUR",
      "beneficiary_id": 11111
    },
    {
      "description": "Payment to Seller B",
      "price": 3000,
      "currency": "EUR",
      "beneficiary_id": 22222
    }
  ],
  "redirect_uri": "https://yoursite.com/return"
}

All payments in a transaction are atomic - either all succeed or all fail.

Transaction Lifecycle

1. Create Transaction

POST /rest/v1/transaction
{
  "payments": [...],
  "redirect_uri": "https://yoursite.com/return"
}

Status: new

2. User Accepts

Three methods:

Redirect to Paysera confirmation page
Use allowance (automatic)
Provide PIN via API

Status: new → waiting

3. Confirm Transaction

PUT /rest/v1/transaction/{transaction_key}/confirm

Status: waiting → confirmed

4. Check Status

GET /rest/v1/transaction/{transaction_key}

Transaction Settings

View Settings Options

Reserve Time Limit

Set how long to wait for confirmation:

{
  "payments": [...],
  "reserve": {
    "for": 1800  // 30 minutes in seconds
  }
}

Default: 30 minutes

Auto-Confirm

Skip manual confirmation step:

{
  "payments": [...],
  "auto_confirm": true
}

When to Use Auto-Confirm

Only use when service cannot fail. Do NOT use for e-commerce, bookings, or limited inventory.

Callback URI

Receive payment notifications:

{
  "payments": [...],
  "callback_uri": "https://yoursite.com/payment-callback"
}

Paysera will POST to this URL when payment status changes.

Transaction with Allowance

View Allowance Usage

Create with Allowance

{
  "payments": [{
    "description": "Monthly subscription",
    "price": 999,
    "currency": "EUR"
  }],
  "allowance": {
    "description": "Premium Subscription",
    "max_price": 999,
    "currency": "EUR",
    "valid": {
      "for": 2592000  // 30 days
    }
  }
}

User accepts allowance once, then you can charge automatically.

Use Existing Allowance

{
  "payments": [{
    "description": "Monthly charge",
    "price": 999
  }],
  "allowance_id": 12345
}

Then reserve using allowance:

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

Transaction Types

View Transaction Types

Standard Payment (type: "page")

Regular payment for goods/services.

{
  "type": "page",
  "payments": [...]
}

Transfer (type: "transfer")

Wallet-to-wallet transfer.

{
  "type": "transfer",
  "payments": [{
    "beneficiary_id": 11111
  }]
}

Donation (type: "donation")

Charitable donation.

{
  "type": "donation",
  "payments": [...]
}

Confirming Transaction

View Confirmation Options

Basic Confirmation

PUT /rest/v1/transaction/{transaction_key}/confirm

Confirm with Price Adjustment

Reduce payment amount before confirming:

PUT /rest/v1/transaction/{transaction_key}/confirm
{
  "payments": [{
    "id": 2988,
    "price": 2500  // Reduced from 2999
  }]
}

Use cases: Discounts, Partial refunds, Adjusted costs

Partial Confirmation

Confirm only some payments:

PUT /rest/v1/transaction/{transaction_key}/confirm
{
  "payments": [
    {"id": 2988, "price": 2999},  // Confirm
    {"id": 2989, "cancel": true}   // Cancel
  ]
}

Revoking Transaction

Cancel a transaction before confirmation:

PUT /rest/v1/transaction/{transaction_key}/revoke

When to revoke: User cancelled, Out of stock, Service unavailable

Status: waiting → canceled

Cannot Revoke After Confirmation

Once confirmed, transaction cannot be revoked.

Transaction Status

Status	Description	Next States
`new`	Just created	`waiting`, `failed`
`waiting`	User accepted, funds reserved	`reserved`, `confirmed`, `canceled`
`reserved`	Confirmed, payments visible	`confirmed`, `done`
`confirmed`	Completed successfully	`done`
`done`	Fully completed	-
`canceled`	Cancelled or revoked	-
`failed`	Failed to process	-

Advanced Topics

Error Handling

Insufficient Funds

{
  "error": "insufficient_funds",
  "error_description": "Wallet balance insufficient for payments"
}

Solution: User needs to add funds

Invalid Allowance

{
  "error": "invalid_allowance",
  "error_description": "Allowance limit exceeded"
}

Solution: Reduce amount or get new allowance

Expired Transaction

{
  "error": "invalid_state",
  "error_description": "Transaction reservation has expired"
}

Solution: Create new transaction

Already Confirmed

{
  "error": "invalid_state",
  "error_description": "Transaction is already confirmed"
}

Solution: Don't try to confirm twice

Password Protection

Require password for sensitive operations:

{
  "payments": [...],
  "password_request": {
    "type": "always"
  }
}

Options: always, standard, none

Common Patterns

Pattern 1: Simple E-Commerce

// 1. Create
const tx = await createTransaction({
  payments: [{
    description: 'Order #1234',
    price: 4999,
    currency: 'EUR'
  }],
  redirect_uri: 'https://myshop.com/payment-return',
  callback_uri: 'https://myshop.com/payment-callback',
  reserve: { for: 1800 }
});

// 2. Redirect user
window.location = getConfirmUrl(tx.transaction_key);

// 3. User returns, check status
const status = await getTransaction(tx.transaction_key);

if (status.status === 'waiting') {
  // 4. Confirm
  await confirmTransaction(tx.transaction_key);
}

Pattern 2: Subscription with Allowance

// Phase 1: Setup (once)
const tx = await createTransaction({
  allowance: {
    description: 'Monthly Subscription',
    max_price: 999,
    valid: { for: 31536000 }  // 1 year
  }
});

// Phase 2: Monthly charges (automatic)
async function chargeMonthly() {
  const tx = await createTransaction({
    payments: [{
      description: 'Monthly Subscription',
      price: 999
    }],
    allowance_id: userAllowanceId
  });
  
  await reserveWithAllowance(tx.transaction_key, walletId);
  await confirmTransaction(tx.transaction_key);
}

Pattern 3: Marketplace Split

const tx = await createTransaction({
  payments: [
    {
      description: 'Seller A - Product',
      price: 7000,
      beneficiary_id: sellerAWallet
    },
    {
      description: 'Seller B - Shipping',
      price: 500,
      beneficiary_id: sellerBWallet
    },
    {
      description: 'Platform Fee',
      price: 500,
      beneficiary_id: platformWallet
    }
  ],
  redirect_uri: 'https://marketplace.com/complete'
});

Monitoring & Debugging

Get Transaction Details

GET /rest/v1/transaction/{transaction_key}

What you get:

Current status
All payments with statuses
Timeline (created, accepted, confirmed)
Error details if failed
Allowance info if used

Check Payment Timeline

{
  "transaction_key": "pDAlAZ3z",
  "created_at": 1698675600,
  "status": "confirmed",
  "payments": [{
    "created_at": 1698675600,
    "status": "done"
  }],
  "reserve": {
    "until": 1698677400  // 30 min from creation
  }
}

Calculate times:

Time to accept: accepted_at - created_at
Time to confirm: confirmed_at - accepted_at
Total time: confirmed_at - created_at

API Reference

Method	Endpoint	Description
`POST`	`/rest/v1/transaction`	Create transaction
`GET`	`/rest/v1/transaction/{key}`	Get transaction details
`PUT`	`/rest/v1/transaction/{key}/confirm`	Confirm transaction
`PUT`	`/rest/v1/transaction/{key}/revoke`	Revoke transaction
`PUT`	`/rest/v1/transaction/{key}/reserve/{wallet}`	Reserve with allowance
`POST`	`/rest/v1/transaction/{key}/reserve`	Reserve with PIN

Full API reference: Wallet API Endpoints

What's Next?

Explore related resources:

Payment Resource - Payment details and management
Allowance Resource - Recurring payment setup
Callbacks - Handle payment notifications
Authorising Transactions - All acceptance methods

Need Help?

Questions? → tech_support@paysera.com
Flow Guide → Transaction Flow
Examples → Code Samples

Quick Reference

Lifecycle: Create → Accept → Confirm → Done
Reserve time: Default 30 minutes
Auto-confirm: Use with caution

Transaction Object​

Creating a Transaction​

Transaction Lifecycle​

Transaction Settings​

Transaction with Allowance​

Transaction Types​

Confirming Transaction​

Revoking Transaction​

Transaction Status​

Advanced Topics​

API Reference​

What's Next?​

Need Help?​