NAME

Lib::Pepper - Perl bindings for the Pepper payment terminal library

SYNOPSIS

use Lib::Pepper;
use Lib::Pepper::Constants qw(:all);
use Lib::Pepper::OptionList;
use Lib::Pepper::Instance;

# Initialize the library
Lib::Pepper->initialize(
    library_path => '',  # Empty for default
);

# Get version information
my $version = Lib::Pepper->version();
print "Pepper version: $version->{string}\n";

# Create an instance for a payment terminal
my $instance = Lib::Pepper::Instance->new(
    terminal_type => PEP_TERMINAL_TYPE_MOCK,  # Or GENERIC_ZVT, HOBEX_ZVT
    instance_id => 1,
);

# Configure the instance
$instance->configure(
    callback => sub {
        my ($event, $option, $instanceHandle, $outputOptions, $inputOptions, $userData) = @_;
        # Handle callback events
    },
    options => {
        sHostName => '192.168.1.100:20007',
        iLanguageValue => PEP_LANGUAGE_ENGLISH,
    },
);

# Perform a transaction
my $result = $instance->transaction(
    transaction_type => PEP_TRANSACTION_TYPE_GOODS_PAYMENT,
    amount => 10_050,  # 100.50 EUR in cents
    currency => PEP_CURRENCY_EUR,
);

# Clean up
$instance = undef;
Lib::Pepper->finalize();

DESCRIPTION

Lib::Pepper provides Perl bindings for the Pepper payment terminal library, which supports ZVT (Zentraler Kreditausschuss Terminal) protocol communication with EFT/POS payment terminals.

This module provides both low-level XS bindings to the C API and high-level object-oriented wrappers for ease of use.

In all likelyhood, you really want to use the simplified bindings in Lib::Pepper::Simple, not the low level stuff.

FEATURES

- Support for Generic ZVT (Terminal Type 118) and Hobex ZVT (Terminal Type 120) - Asynchronous callback-based operation - Complete API coverage (initialization, configuration, transactions, settlements) - Object-oriented interface with Lib::Pepper::Instance - Option list management with Lib::Pepper::OptionList - Comprehensive error handling with Lib::Pepper::Exception - 200+ exported constants for operations, currencies, and error codes

METHODS

initialize(%params)

Initializes the Pepper library. Must be called before any other operations.

Lib::Pepper->initialize(
    library_path => '',           # Optional: path to libpepcore.so
    config_xml   => undef,        # Optional: XML configuration string
    license_xml  => undef,        # Optional: XML license string
);

Parameters: - library_path: Optional path to pepcore library (empty for default) - config_xml: Optional XML configuration (undef to use config file) - license_xml: Optional XML license (undef to use license file)

Returns: Terminal type option list handle

Throws: Exception on failure

finalize()

Finalizes and cleans up the Pepper library. Call when done with all operations.

Lib::Pepper->finalize();

Returns: 1 on success

Throws: Exception on failure

version()

Returns version information about the Pepper library.

my $version = Lib::Pepper->version();
print "Version: $version->{string}\n";
print "API version: $version->{api}\n";

Returns: Hashref with keys: major, minor, service, revision, api, osArch, releaseType, configType, string

UTILITY METHODS

dataDir()

Returns the installation directory containing library data files.

my $dir = Lib::Pepper->dataDir();

Searches for the data directory in two locations:

1. Installed location: $PREFIX/lib/perl5/auto/Lib/Pepper/ 2. Development location: share/ relative to module path

Returns: Directory path as string, or undef if not found

cardtypesFile()

Returns the full path to the installed pepper_cardtypes.xml file.

my $path = Lib::Pepper->cardtypesFile();

This file contains card type definitions and is required for terminal configuration. Use the returned path in your config XML or pass it to configuration methods.

Returns: File path as string, or undef if not found

LOW-LEVEL FUNCTIONS

The following low-level XS functions are available for direct use. They can be imported individually or with :all tag.

NOTE: Most users should use Lib::Pepper::Instance or Lib::Pepper::Simple instead of these low-level functions.

Library Management

pepInitialize($libraryPath, $configXml, $licenseXml)

Initializes the Pepper payment library.

my $result = pepInitialize($libPath, $configXml, $licenseXml);

Parameters:

$libraryPath - Path to libpepcore.so (or empty string for installed library)
$configXml - Configuration XML content as string
$licenseXml - License XML content as string

Returns: Result code (0 = success, negative = error)

pepFinalize()

Finalizes and shuts down the Pepper library.

my $result = pepFinalize();

Call this when completely done with the library. Frees all library resources.

Returns: Result code (0 = success, negative = error)

pepVersion()

Queries the Pepper library version information.

my ($result, $major, $minor, $service, $revision, $api,
    $osArch, $releaseType, $configType) = pepVersion();

Returns: List of version components

Instance Management

pepCreateInstance($terminalType, $instanceId)

Creates a new Pepper instance for a payment terminal.

my ($result, $handle) = pepCreateInstance($termType, $id);

Parameters:

$terminalType - Terminal type constant (e.g., PEP_TERMINAL_TYPE_GENERIC_ZVT)
$instanceId - Unique instance identifier string

Returns: ($result, $handle) - Result code and instance handle

pepFreeInstance($instance)

Frees a Pepper instance.

my $result = pepFreeInstance($handle);

Releases all resources associated with the instance.

Returns: Result code

pepConfigureWithCallback($instance, $inputOptions, $callback, $userData)

Configures an instance with callback and options.

my ($result, $outputOptions) = pepConfigureWithCallback(
    $handle, $optionList, \&callback, $userData
);

Parameters:

$instance - Instance handle
$inputOptions - Option list handle with configuration
$callback - Code reference for event callbacks
$userData - Custom data passed to callbacks

Returns: ($result, $outputOptions) - Result code and output option list handle

Operation Workflow

All operations follow a 4-step workflow: prepare, start, execute, finalize.

pepPrepareOperation($instance, $operation, $inputOptions)

Executes the "prepare" step of an operation.

my ($result, $opHandle, $outputOptions) = pepPrepareOperation(
    $instance, PEP_OPERATION_TRANSACTION, $optionList
);

Parameters:

$instance - Instance handle
$operation - Operation type constant
$inputOptions - Option list handle with operation parameters

Returns: ($result, $operationHandle, $outputOptions)

pepStartOperation($instance, $operation, $inputOptions)

Executes the "start" step of an operation.

my ($result, $opHandle, $outputOptions) = pepStartOperation(
    $instance, $operation, $optionList
);

See pepPrepareOperation for parameter details.

pepExecuteOperation($instance, $operation, $inputOptions)

Executes the "execute" step of an operation.

my ($result, $opHandle, $outputOptions) = pepExecuteOperation(
    $instance, $operation, $optionList
);

See pepPrepareOperation for parameter details.

pepFinalizeOperation($instance, $operation, $inputOptions)

Executes the "finalize" step of an operation.

my ($result, $opHandle, $outputOptions) = pepFinalizeOperation(
    $instance, $operation, $optionList
);

See pepPrepareOperation for parameter details.

pepOperationStatus($instance, $operation, $waitForCompletion)

Checks the status of an operation.

my ($result, $status) = pepOperationStatus($instance, $opHandle, 1);

Parameters:

$instance - Instance handle
$operation - Operation handle
$waitForCompletion - Boolean: 1 to block until complete, 0 to return immediately

Returns: ($result, $status) - Result code and completion status

Utilities

pepUtility($instance, $inputOptions)

Executes a utility operation (synchronous).

my ($result, $outputOptions) = pepUtility($instance, $optionList);

Used for terminal utility functions like status queries, configuration changes.

Returns: ($result, $outputOptions)

pepAuxiliary($instance, $inputOptions)

Executes an auxiliary operation (synchronous).

my ($result, $outputOptions) = pepAuxiliary($instance, $optionList);

Used for terminal-specific auxiliary functions.

Returns: ($result, $outputOptions)

pepDownloadLicense($inputOptions)

Downloads a license from the license server.

my ($result, $outputOptions) = pepDownloadLicense($optionList);

Requires license server credentials in input options.

Returns: ($result, $outputOptions)

Option Lists

Option lists are key-value containers for parameters and results. See Lib::Pepper::OptionList for object-oriented interface.

pepOptionListCreate()

Creates a new option list.

my $handle = pepOptionListCreate();

Returns: Option list handle

pepOptionListGetStringElement($list, $key)

Retrieves a string value from an option list.

my ($result, $value) = pepOptionListGetStringElement($list, $key);

Returns: ($result, $value)

pepOptionListGetIntElement($list, $key)

Retrieves an integer value from an option list.

my ($result, $value) = pepOptionListGetIntElement($list, $key);

Returns: ($result, $value)

pepOptionListGetChildOptionListElement($list, $key)

Retrieves a child option list from an option list.

my ($result, $childList) = pepOptionListGetChildOptionListElement($list, $key);

Returns: ($result, $childHandle)

pepOptionListAddStringElement($list, $key, $value)

Adds a string value to an option list.

my $result = pepOptionListAddStringElement($list, $key, $value);

Returns: Result code

pepOptionListAddIntElement($list, $key, $value)

Adds an integer value to an option list.

my $result = pepOptionListAddIntElement($list, $key, $value);

Returns: Result code

pepOptionListAddChildOptionListElement($list, $key, $childList)

Adds a child option list to an option list.

my $result = pepOptionListAddChildOptionListElement($list, $key, $childList);

Returns: Result code

pepOptionListGetElementList($list)

Retrieves all keys from an option list.

my ($result, @keys) = pepOptionListGetElementList($list);

Returns: ($result, @keys)

Helper Functions

isValidHandle($handle)

Checks if a handle is valid.

if(isValidHandle($handle)) {
    # Handle is valid
}

Returns: 1 if valid, 0 if invalid

isSuccess($result)

Checks if a result code indicates success.

if(isSuccess($result)) {
    # Operation succeeded
}

Returns: 1 if success, 0 if failure

isFailure($result)

Checks if a result code indicates failure.

if(isFailure($result)) {
    # Operation failed
}

Returns: 1 if failure, 0 if success

MODULES

Lib::Pepper::Constants: Exports 200+ constants for operations, states, currencies, error codes
Lib::Pepper::Exception: Error handling and exception management
Lib::Pepper::OptionList: Object-oriented wrapper for option lists
Lib::Pepper::Instance: High-level instance management
Lib::Pepper::ZVT::Generic: Helpers for Generic ZVT terminals (Type 118)
Lib::Pepper::ZVT::Hobex: Helpers for Hobex ZVT terminals (Type 120)

EXPORT

None by default. Functions can be imported individually or with the :all tag.

WARNING: AI USE

Warning, this file was generated with the help of the 'Claude' AI (an LLM/large language model by the USA company Anthropic PBC) in November 2025. It was not reviewed line-by-line by a human, only on a functional level. It is therefore not up to the usual code quality and review standards. Different copyright laws may also apply, since the program was not created by humans but mostly by a machine, therefore the laws requiring a human creative process may or may not apply. Laws regarding AI use are changing rapidly. Before using the code provided in this file for any of your projects, make sure to check the current version of your local laws.

AUTHOR

Rene Schickbauer, <cavac@cpan.org>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.42.0 or, at your option, any later version of Perl 5 you may have available.

To install Lib::Pepper, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Lib::Pepper

CPAN shell

perl -MCPAN -e shell
install Lib::Pepper

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

FEATURES

METHODS

initialize(%params)

finalize()

version()

UTILITY METHODS

dataDir()

cardtypesFile()

LOW-LEVEL FUNCTIONS

Library Management

pepInitialize($libraryPath, $configXml, $licenseXml)

pepFinalize()

pepVersion()

Instance Management

pepCreateInstance($terminalType, $instanceId)

pepFreeInstance($instance)

pepConfigureWithCallback($instance, $inputOptions, $callback, $userData)

Operation Workflow

pepPrepareOperation($instance, $operation, $inputOptions)

pepStartOperation($instance, $operation, $inputOptions)

pepExecuteOperation($instance, $operation, $inputOptions)

pepFinalizeOperation($instance, $operation, $inputOptions)

pepOperationStatus($instance, $operation, $waitForCompletion)

Utilities

pepUtility($instance, $inputOptions)

pepAuxiliary($instance, $inputOptions)

pepDownloadLicense($inputOptions)

Option Lists

pepOptionListCreate()

pepOptionListGetStringElement($list, $key)

pepOptionListGetIntElement($list, $key)

pepOptionListGetChildOptionListElement($list, $key)

pepOptionListAddStringElement($list, $key, $value)

pepOptionListAddIntElement($list, $key, $value)

pepOptionListAddChildOptionListElement($list, $key, $childList)

pepOptionListGetElementList($list)

Helper Functions

isValidHandle($handle)

isSuccess($result)

isFailure($result)

MODULES

EXPORT

WARNING: AI USE

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions