Payment Resource

The Payment Resource represents a transfer of funds from one wallet (payer) to another wallet (beneficiary). Payments are always part of a transaction.

Quick Start

New to payments? Start with Payment Concepts to understand the basics.

Payment Object

Structure

{
  "id": 2988,
  "transaction_key": "pDAlAZ3z",
  "created_at": 1698675600,
  "status": "done",
  "type": "page",
  "wallet": 14471,
  "confirmed_at": 1698675680,
  "description": "Payment for Order #1234",
  "price": 2999,
  "price_decimal": "29.99",
  "currency": "EUR",
  "beneficiary": 11111,
  "payer": 14471,
  "commission": {
    "in_commission": 0,
    "out_commission": 0
  },
  "parameters": {
    "order_id": "1234",
    "item_count": 3
  }
}

View Fields Reference

Field	Type	Description
`id`	integer	Payment ID (unique)
`transaction_key`	string	Transaction this payment belongs to
`created_at`	timestamp	When payment was created
`status`	string	Payment status (`new`, `waiting`, `reserved`, `done`, `canceled`)
`type`	string	Payment type (`page`, `transfer`, etc.)
`wallet`	integer	Payer's wallet ID
`confirmed_at`	timestamp	When payment was confirmed (if confirmed)
`freeze_until`	timestamp	If set, payment frozen until this time
`description`	string	Required. Payment description
`price`	integer	Required. Amount in cents
`price_decimal`	string	Amount in decimal format (e.g., "29.99")
`currency`	string	Required. 3-letter currency code (e.g., "EUR")
`beneficiary`	integer	Beneficiary wallet ID
`payer`	integer	Payer wallet ID
`commission`	object	Commission details
`parameters`	object	Custom key-value parameters

Creating a Payment

View Payment Creation Examples

Payments are created as part of a transaction. You cannot create a standalone payment.

Simple Payment

POST /rest/v1/transaction

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

Itemized Payment

{
  "payments": [{
    "description": "Shopping cart payment",
    "items": [
      {
        "title": "Premium Plan - 1 Month",
        "description": "Full access to all features",
        "price": 999,
        "quantity": 1,
        "image_uri": "https://example.com/premium.jpg"
      },
      {
        "title": "Extra Storage - 50GB",
        "price": 299,
        "quantity": 2
      }
    ]
  }],
  "redirect_uri": "https://yoursite.com/return"
}

Total Price: Automatically calculated from items (999 + 2×299 = 1597 cents = 15.97 EUR)

Payment with Beneficiary

Specify where money should go:

{
  "payments": [{
    "description": "Transfer to friend",
    "price": 5000,
    "currency": "EUR",
    "beneficiary_id": 11111  // Specific wallet
  }]
}

// Or by email/phone:
{
  "payments": [{
    "description": "Payment to contractor",
    "price": 25000,
    "currency": "EUR",
    "email": "contractor@example.com"  // By email
  }]
}

Unregistered Beneficiaries

If email/phone isn't registered, beneficiary will receive invitation to register and claim the payment.

Payment Types

View Payment Types

Standard Payment (type: "page")

Regular payment for goods/services.

{
  "description": "Order #1234",
  "price": 4999,
  "type": "page"
}

Transfer (type: "transfer")

Direct wallet-to-wallet transfer.

{
  "description": "Money transfer",
  "price": 10000,
  "type": "transfer",
  "beneficiary_id": 11111
}

Donation (type: "donation")

Charitable donation.

{
  "description": "Monthly donation",
  "price": 2000,
  "type": "donation"
}

Payment Items

View Item Details

For detailed itemization, use items instead of simple price:

Item Object

{
  "title": "Product name",
  "description": "Product description",
  "price": 1999,
  "quantity": 2,
  "image_uri": "https://example.com/product.jpg",
  "parameters": {
    "sku": "PROD-001",
    "category": "electronics"
  }
}

Item Fields

Field	Type	Required	Description
`title`	string	✅ Yes	Item name
`description`	string	⚠️ Optional	Item description
`price`	integer	✅ Yes	Price in cents (per unit)
`quantity`	integer	✅ Yes	Quantity
`image_uri`	string	⚠️ Optional	Item image URL
`parameters`	object	⚠️ Optional	Custom metadata

Example: Shopping Cart

{
  "payments": [{
    "description": "Online Store Purchase",
    "items": [
      {
        "title": "Laptop",
        "description": "15-inch, 16GB RAM",
        "price": 89999,
        "quantity": 1,
        "image_uri": "https://shop.com/laptop.jpg"
      },
      {
        "title": "Mouse",
        "price": 2999,
        "quantity": 2
      },
      {
        "title": "USB Cable",
        "price": 599,
        "quantity": 3
      }
    ]
  }]
}

Total: 89999 + 2×2999 + 3×599 = 97,794 cents = 977.94 EUR

Commission

View Commission Options

Add fees to payments:

Outgoing Commission - Fee paid BY payer (added to total):

{
  "payments": [{
    "price": 10000,
    "commission": {
      "out_commission": 500  // +5 EUR fee
    }
  }]
}

Payer pays: 105 EUR | Beneficiary receives: 100 EUR

Incoming Commission - Fee deducted FROM beneficiary:

{
  "payments": [{
    "price": 10000,
    "commission": {
      "in_commission": 300  // -3 EUR from beneficiary
    }
  }]
}

Payer pays: 100 EUR | Beneficiary receives: 97 EUR

Both Commissions

{
  "payments": [{
    "price": 10000,
    "commission": {
      "out_commission": 500,   // +5 EUR from payer
      "in_commission": 300     // -3 EUR from beneficiary
    }
  }]
}

Payer pays: 105 EUR | Beneficiary receives: 97 EUR | Total fees: 8 EUR

Custom Parameters

Add custom metadata to payments:

{
  "payments": [{
    "description": "Order payment",
    "price": 4999,
    "parameters": {
      "order_id": "ORD-12345",
      "customer_id": "CUST-98765",
      "shipping_method": "express",
      "warehouse": "EU-WEST-1"
    }
  }]
}

Use cases: Order IDs, Customer references, Internal tracking, Integration metadata

Parameters in Callbacks

Parameters are included in payment callbacks, making it easy to match payments with your internal records.

Frozen Payments

View Frozen Payment Details

Hold funds without immediately transferring them:

Creating Frozen Payment

{
  "payments": [{
    "description": "Hotel reservation deposit",
    "price": 20000,
    "freeze_until": 1735689600  // Unix timestamp
  }]
}

Status flow:

User accepts → Status: waiting (funds reserved)
You confirm → Status: reserved (funds frozen)
Later: Finalize or cancel

Finalize Payment

PUT /rest/v1/payment/{payment_id}/finalize

// Optional: Reduce amount
{
  "price": 15000  // Reduced from 20000
}

Cancel Payment

DELETE /rest/v1/payment/{payment_id}

Use cases: Hotel reservations, Car rentals, Pre-authorizations, Deposits

Payment Status

Status Lifecycle

new → waiting → reserved → done
  ↓       ↓          ↓
failed  canceled  canceled

Status	Meaning	Funds State
`new`	Just created	Not reserved
`waiting`	User accepted	Reserved, not visible to beneficiary
`reserved`	Confirmed	Transferred or frozen
`done`	Completed	Transferred
`canceled`	Cancelled	Released/refunded
`failed`	Failed	Not reserved

Getting Payment Details

View API Calls

Get Single Payment

GET /rest/v1/payment/{payment_id}

Response:

{
  "id": 2988,
  "status": "done",
  "description": "Order payment",
  "price": 2999,
  "currency": "EUR",
  "created_at": 1698675600,
  "confirmed_at": 1698675680
}

Get Payments by Transaction

GET /rest/v1/transaction/{transaction_key}

Response includes all payments:

{
  "transaction_key": "pDAlAZ3z",
  "status": "confirmed",
  "payments": [
    {"id": 2988, "price": 2999},
    {"id": 2989, "price": 1499}
  ]
}

Common Patterns

View Real-World Patterns

Pattern 1: E-Commerce Checkout

{
  "payments": [{
    "description": "Order #ORD-12345",
    "items": [
      {"title": "Product A", "price": 2999, "quantity": 2},
      {"title": "Product B", "price": 1499, "quantity": 1}
    ],
    "commission": {
      "out_commission": 250  // Processing fee
    },
    "parameters": {
      "order_id": "ORD-12345",
      "shipping_method": "standard"
    }
  }],
  "redirect_uri": "https://myshop.com/order-complete"
}

Pattern 2: Marketplace Split Payment

{
  "payments": [
    {
      "description": "Payment to Seller A",
      "price": 5000,
      "beneficiary_id": 11111,
      "parameters": {"seller": "A"}
    },
    {
      "description": "Payment to Seller B",
      "price": 3000,
      "beneficiary_id": 22222,
      "parameters": {"seller": "B"}
    },
    {
      "description": "Platform fee",
      "price": 500,
      "beneficiary_id": 33333,
      "parameters": {"type": "platform_fee"}
    }
  ]
}

Pattern 3: Subscription with Trial

// Month 1: Trial (reduced price)
{
  "payments": [{
    "description": "Premium - Trial Month",
    "price": 99,
    "parameters": {
      "plan": "premium",
      "period": "trial"
    }
  }],
  "allowance_id": userAllowanceId
}

// Month 2+: Regular price
{
  "payments": [{
    "description": "Premium - Monthly",
    "price": 999,
    "parameters": {
      "plan": "premium",
      "period": "regular"
    }
  }],
  "allowance_id": userAllowanceId
}

Error Handling

View Common Errors

insufficient_funds

{
  "error": "insufficient_funds",
  "error_description": "Wallet balance is insufficient for this payment"
}

Solution: Ask user to add funds or reduce payment amount

invalid_currency

{
  "error": "invalid_parameters",
  "error_description": "Currency must be 3-letter code (e.g., EUR)"
}

Solution: Use valid ISO 4217 currency code

price_required

{
  "error": "invalid_parameters",
  "error_description": "Either price or items must be provided"
}

Solution: Provide price or items array

API Reference

Method	Endpoint	Description
`POST`	`/rest/v1/transaction`	Create payment (in transaction)
`GET`	`/rest/v1/payment/{id}`	Get payment details
`PUT`	`/rest/v1/payment/{id}/finalize`	Finalize frozen payment
`DELETE`	`/rest/v1/payment/{id}`	Cancel frozen payment

Full API reference: Wallet API Endpoints

What's Next?

Learn about related resources:

Transaction Resource - Manage transaction lifecycle
Allowance Resource - Set up recurring payments
Commission Resource - Handle fees and charges
Payment Examples - See complete implementations

Need Help?

Questions? → tech_support@paysera.com
Concepts → Payment Concepts
Examples → Code Samples

Quick Reference

Required fields: description, price, currency
Optional: items, beneficiary_id, commission, parameters, freeze_until

Payment Object​

Creating a Payment​

Payment Types​

Payment Items​

Commission​

Custom Parameters​

Frozen Payments​

Payment Status​

Getting Payment Details​

Common Patterns​

Error Handling​

API Reference​

What's Next?​

Need Help?​