Skip to main content

Reservation Codes

Reservation Codes allow you to generate unique payment codes that users can enter in the Paysera app to make payments without clicking links or scanning QR codes.

Use Cases

Phone-based payments, Manual code entry, Customer service, Physical receipts, Voice orders

What are Reservation Codes?​

A reservation code is a unique alphanumeric code (e.g., ABC-123-XYZ) that users can manually enter in their Paysera wallet to complete a payment.

Creating Reservation Codes​

View Code Generation Examples

Basic Code Generation

POST /rest/v1/payment-code

{
  "amount": 2999,
  "currency": "EUR",
  "description": "Order #1234"
}

Response:

{
  "code": "PAY-2024-ABC123",
  "amount": 2999,
  "currency": "EUR",
  "valid_until": 1698761999,
  "status": "active"
}

Code with Details

{
  "amount": 5000,
  "currency": "EUR",
  "description": "Hotel Reservation - Room 405",
  "valid_for": 3600,  // Valid for 1 hour
  "reference": "RES-2024-405",
  "beneficiary_wallet_id": 11111,
  "items": [
    {
      "title": "Room rental - 2 nights",
      "price": 4000,
      "quantity": 1
    },
    {
      "title": "City tax",
      "price": 1000,
      "quantity": 1
    }
  ]
}

Code Formats

Default: PAY-2024-ABC123

  • Prefix: PAY-
  • Year: 2024-
  • Unique ID: ABC123

Custom (shorter for voice): ABC123

Code Lifecycle​

Statuses

StatusDescriptionActions Available
activeValid, can be usedCancel
usedPayment made with codeNone
expiredValidity period passedNone
canceledManually canceledNone

Validity Period

Default: 24 hours

Custom:

{
  "valid_for": 1800  // 30 minutes
  // OR
  "valid_until": 1698761999  // Unix timestamp
}

Check Code Status

GET /rest/v1/payment-code/{code}

Displaying Codes to Users​

View Display Methods

On Screen

const code = await generatePaymentCode({
  amount: 2999,
  description: 'Order #1234'
});

console.log(`
  Payment Code: ${code.code}
  Amount: ${code.amount / 100} EUR
  Valid until: ${new Date(code.valid_until * 1000).toLocaleString()}
  
  Enter this code in Paysera app to pay.
`);

In Receipt

====================================
      YOUR PAYMENT CODE
====================================

Code:     PAY-2024-ABC123
Amount:   29.99 EUR
Valid:    1 hour
Order:    #1234

To pay:
1. Open Paysera app
2. Go to Payments
3. Enter code
4. Confirm payment

====================================

Via Phone/Voice

// Generate short code for voice
const code = await generatePaymentCode({
  amount: 1500,
  description: 'Phone order',
  code_format: 'short'
});

// Read to customer
console.log(`Your payment code is: ${code.code.split('').join(' ')}`);
// "Your payment code is: A B C 1 2 3"

Use Cases​

View Real-World Use Cases

Use Case 1: Hotel Check-In

async function generateCheckInPayment(reservation) {
  const code = await generatePaymentCode({
    amount: reservation.totalAmount,
    currency: 'EUR',
    description: `Hotel Stay - Room ${reservation.roomNumber}`,
    reference: reservation.confirmationNumber,
    valid_for: 3600,  // 1 hour to check in
    items: [
      {
        title: `Room ${reservation.roomNumber} - ${reservation.nights} nights`,
        price: reservation.roomRate * reservation.nights,
        quantity: 1
      },
      {
        title: 'City tax',
        price: reservation.tax,
        quantity: 1
      }
    ]
  });
  
  await printReceipt({
    guest: reservation.guestName,
    room: reservation.roomNumber,
    paymentCode: code.code,
    amount: code.amount / 100,
    validUntil: code.valid_until
  });
  
  return code;
}

Use Case 2: Phone Order

async function processPhoneOrder(order, customerPhone) {
  const code = await generatePaymentCode({
    amount: order.total,
    description: `Phone order - ${order.items.length} items`,
    reference: order.orderNumber,
    code_format: 'short',
    valid_for: 1800  // 30 minutes
  });
  
  // Send via SMS
  await sendSMS({
    to: customerPhone,
    message: `Your payment code: ${code.code}. Amount: ${order.total/100} EUR. Valid for 30 min.`
  });
  
  return code;
}

Use Case 3: Customer Service

async function createServicePayment(issue) {
  const code = await generatePaymentCode({
    amount: issue.amount,
    description: `Support ticket #${issue.ticketNumber}`,
    reference: issue.ticketNumber,
    valid_for: 86400  // 24 hours
  });
  
  console.log(`
    Agent: "I've created a payment code for you."
    Code: ${code.code}
    Amount: ${issue.amount / 100} EUR
    Valid: 24 hours
  `);
  
  return code;
}

Advanced Topics​

Canceling Codes

Cancel unused code:

DELETE /rest/v1/payment-code/{code}

When to cancel: Order canceled, Customer changed mind, Code given by mistake

Example

async function cancelOrder(orderId) {
  const order = await getOrder(orderId);
  
  if (order.paymentCode && order.paymentStatus === 'pending') {
    await cancelPaymentCode(order.paymentCode);
  }
  
  await updateOrder(orderId, { status: 'canceled' });
}
Monitoring Codes

Track Code Usage

class CodeMonitor {
  async getCodeStats(period) {
    return {
      generated: await this.countGenerated(period),
      used: await this.countUsed(period),
      expired: await this.countExpired(period),
      canceled: await this.countCanceled(period),
      usageRate: await this.calculateUsageRate(period)
    };
  }
  
  async calculateUsageRate(period) {
    const total = await this.countGenerated(period);
    const used = await this.countUsed(period);
    return (used / total * 100).toFixed(2);
  }
}
Alternatives

QR Codes - For visual payments:

const qrCode = await generatePaymentQR({
  amount: 2999,
  description: 'Order #1234'
});

Better when: In-person, visual medium available

Direct Links - For digital payments:

const tx = await createTransaction({...});
const paymentUrl = getConfirmationUrl(tx.transaction_key);

Better when: Email, SMS, messaging apps

Advantages & Disadvantages​

✅ Advantages

  • No internet needed - User can write down code
  • Phone-friendly - Easy to communicate
  • Simple process - Just enter code
  • Works offline - Generate ahead of time
  • Physical receipts - Can print

⚠️ Disadvantages

  • Manual entry - User must type code
  • Can expire - Time-limited
  • Requires Paysera app - User must have app
  • Less automated - More manual than links/QR
  • Typing errors - User might mistype

What's Next?​

You've completed all Integration Guides! 🎉

Explore more:

  1. Authorising Transactions - All acceptance methods
  2. Callbacks - Handle payment notifications
  3. Transaction Requests - Request payments from users

Return to:

  • Payment Resource - Payment API details (see API Resources in sidebar)
  • Transaction Resource - Transaction management (see API Resources in sidebar)
  • Samples & Examples - Complete code examples

Need Help?​

Quick Reference

Format: PAY-2024-ABC123
Validity: Default 24 hours
Use: Enter in Paysera app
Best for: Phone orders, receipts, voice communication