/ 
Lib-Pepper-0.5
River stage zero No dependents
/ examples/README.md

Lib::Pepper Examples

This directory contains example scripts demonstrating how to use the Lib::Pepper module for payment terminal integration.

Setup Instructions

1. Install the Module

First, build and install the Lib::Pepper module:

cd /path/to/Lib-Pepper
perl Makefile.PL
make
make test
sudo make install  # Or install to local::lib

This will install:

2. Configure the Examples

a. Copy the Configuration Template

cd examples/
cp config/pepper_config.xml.example config/pepper_config.xml

The configuration file uses relative paths and is already set up for the examples directory structure.

b. Verify Directory Structure

The following directories should exist (created automatically if missing):

examples/
├── config/
│   ├── pepper_config.xml           # Your config (copied from .example)
│   ├── pepper_config.xml.example   # Template
│   └── pepper_cardtypes.xml        # Card types database
├── data/
│   ├── logging/
│   │   └── archive/
│   └── runtime/
└── *.pl                            # Example scripts

c. Obtain a License File

Contact your Pepper library vendor (treibauf AG) to obtain a license file. The license file path should be specified in the examples or passed as an XML string.

Default license location expected by examples:

/home/cavac/src/pepperclient/pepper_license_8v5r22cg.xml

You can modify this path in each example script.

3. Run the Examples

Simple Transaction Example

Demonstrates the high-level API with automatic transaction workflow:

cd examples/
perl simple_transaction.pl

What it does:

Manual Workflow Example

Demonstrates the low-level 4-step operation workflow:

cd examples/
perl manual_workflow.pl

What it does:

Example Scripts

simple_transaction.pl

Purpose: Quick start example using high-level API

Key Features:

Terminal Type: Mock terminal (PEP_TERMINAL_TYPE_MOCK)

manual_workflow.pl

Purpose: Advanced example with full control over operation steps

Key Features:

Terminal Type: Mock terminal (PEP_TERMINAL_TYPE_MOCK)

real_terminal_test.pl

Purpose: Test payment processing with a real payment terminal (GP PAY)

Key Features:

Terminal Type: Generic ZVT (PEP_TERMINAL_TYPE_GENERIC_ZVT)

Usage:

# Test a 1.00 EUR payment
perl real_terminal_test.pl

# Or specify custom amount in cents
AMOUNT=500 perl real_terminal_test.pl  # 5.00 EUR

What it returns on success:

void_payment.pl

Purpose: Intelligently cancel a payment (automatically handles VOID or REFUND)

Key Features:

Terminal Type: Generic ZVT (PEP_TERMINAL_TYPE_GENERIC_ZVT)

Usage:

# Interactive mode (prompts for input)
perl void_payment.pl

# Command line mode
perl void_payment.pl <trace_number> <amount_in_cents>

# Example: Cancel transaction with trace 1007, amount 1.00 EUR
# Works for both same-day (VOID) and next-day (REFUND) cancellations
perl void_payment.pl 1007 100

How It Works:

  1. Attempts VOID (instant, no money moves)
  2. If VOID fails because transaction is settled → Automatically tries REFUND
  3. Shows clear results: which operation was used and outcome

Important Notes:

Example Output:

⚠  VOID failed because: transaction already settled
↻  AUTOMATICALLY RETRYING AS REFUND...

✓✓✓ REFUND SUCCESSFUL - MONEY WILL BE RETURNED ✓✓✓
✓ Customer will receive refund in 3-5 business days.

Workflow:

  1. Run real_terminal_test.pl to make a payment → Note the Trace Number
  2. Run void_payment.pl with that trace number → Automatically cancels (VOID or REFUND)
  3. Check output to see which operation was used

void_transaction_DOCUMENTATION.pl

Purpose: Documentation and code examples for void operations

Key Features:

This is documentation only - use void_payment.pl for actual void operations.

end_of_day_settlement.pl

Purpose: Perform end-of-day settlement (batch close)

Key Features:

Terminal Type: Generic ZVT (PEP_TERMINAL_TYPE_GENERIC_ZVT)

Usage:

# Run at end of business day
perl end_of_day_settlement.pl

What Settlement Does:

  1. ✓ Finalizes all authorized payments
  2. ✓ Submits batch to payment processor
  3. ✓ Initiates fund transfer to your bank account
  4. ✓ Prints settlement reports (keep for reconciliation!)
  5. ✓ Clears terminal's transaction buffer
  6. ⚠ After settlement, VOID operations become REFUND operations

When to Run:

Settlement Reports Show:

IMPORTANT: Keep settlement reports for accounting and reconciliation!

Complete Daily Workflow

Here's the typical daily payment workflow:

Morning - Start of Day:

# Optional: Check terminal is ready
perl check_terminal_connection.pl

During the Day - Processing Payments:

# For each customer payment
perl real_terminal_test.pl

# If customer cancels (same day only!):
perl void_payment.pl <trace_number> <amount>

Evening - End of Day:

# CRITICAL: Finalize all transactions
perl end_of_day_settlement.pl

After Settlement:

Configuration Details

pepper_config.xml

The configuration file controls:

All paths in the example config are relative to the examples/ directory.

Logging

Logs are written to ./data/logging/ and include:

Check logs if examples fail to understand what went wrong.

Terminal Types

The examples use mock terminals for demonstration. For production use, change to real terminal types:

Generic ZVT Terminal (Type 118)

my $instance = Lib::Pepper::Instance->new(
    terminal_type => PEP_TERMINAL_TYPE_GENERIC_ZVT,
    instance_id   => 1,
);

$instance->configure(
    callback => $callback,
    options  => {
        sHostName                => '192.168.1.100:20007',  # Terminal IP:port
        iLanguageValue           => PEP_LANGUAGE_ENGLISH,
        sPosIdentificationString => '1234',
        iTicketWidthValue        => 40,
    },
);

Hobex ZVT Terminal (Type 120)

my $instance = Lib::Pepper::Instance->new(
    terminal_type => PEP_TERMINAL_TYPE_HOBEX_ZVT,
    instance_id   => 1,
);

Configuration is similar to Generic ZVT.

Mock Terminal Limitations

IMPORTANT: The mock terminal (TT999) has limited functionality:

⚠️ Mock terminals are designed primarily for card recognition testing and configuration validation

What works with mock terminals:

What does NOT work with mock terminals:

For transaction testing, use real ZVT terminals (Generic or Hobex).

The state transition errors you may see with mock terminals are expected behavior and do not indicate a problem with the Lib::Pepper module.

Troubleshooting

"Config file not found" Error

Solution: Copy the example config:

cp config/pepper_config.xml.example config/pepper_config.xml

"Library initialization failed with code: -103"

Possible causes:

Solution:

  1. Check license file path
  2. Ensure all directories in config exist
  3. Check data/logging/ and data/runtime/ are writable

"Invalid state transition (code: -1301)" During Transactions

Cause: Mock terminal limitation

Solution:

"Cannot load library"

Cause: Shared libraries not found

Solution:

  1. Run make install to install libraries
  2. Verify library_path is set to '' (empty string) in examples
  3. Check RPATH configuration: ldd /path/to/Pepper.so

Permission Errors in data/

Cause: Directories not writable

Solution:

chmod -R 755 data/

Real-World Usage

For production payment processing:

  1. Obtain proper hardware: Generic ZVT or Hobex ZVT terminal
  2. Connect terminal: Via serial port, USB, or TCP/IP
  3. Configure connection: Set sHostName to terminal address
  4. Test with small amounts: Verify terminal responds correctly
  5. Implement proper error handling: Handle all callback events
  6. Log transactions: For compliance and debugging

Support

Pepper Library Support

Contact treibauf AG for Pepper library support:

Lib::Pepper Module Issues

For issues with the Perl module itself:

Additional Resources

License

The examples are provided as part of the Lib::Pepper distribution. Pepper library license terms apply for production use.