NAME

Lib::Pepper::Instance - High-level object-oriented wrapper for Pepper terminal instances

SYNOPSIS

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

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

# Create a terminal instance
my $instance = Lib::Pepper::Instance->new(
    terminal_type => PEP_TERMINAL_TYPE_MOCK,
    instance_id   => 1,
);

# Configure with callback
$instance->configure(
    callback => sub {
        my ($event, $option, $instanceHandle, $outputOptions, $inputOptions, $userData) = @_;
        print "Callback event: $event, option: $option\n";
    },
    options => {
        sHostName      => '192.168.1.100:20007',
        iLanguageValue => PEP_LANGUAGE_ENGLISH,
    },
);

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

print "Transaction status: $result->{status}\n";

# Perform settlement
my $settlement = $instance->settlement(
    options => {},
);

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

DESCRIPTION

Lib::Pepper::Instance provides a high-level object-oriented interface for managing Pepper payment terminal instances. It wraps the low-level XS functions and provides convenient methods for common operations.

This class handles the complete lifecycle of a terminal instance, from creation through configuration, operations, and cleanup.

METHODS

new(%params)

Constructor. Creates a new terminal instance.

my $instance = Lib::Pepper::Instance->new(
    terminal_type => PEP_TERMINAL_TYPE_MOCK,      # Required
    instance_id   => 1,                           # Optional, default: 1
);

Parameters:

terminal_type (required)

Terminal type constant. Common values:

- PEP_TERMINAL_TYPE_MOCK (18) - Mock terminal for testing - PEP_TERMINAL_TYPE_GENERIC_ZVT (118) - Generic ZVT terminal - PEP_TERMINAL_TYPE_HOBEX_ZVT (120) - Hobex ZVT terminal

instance_id (optional)

Unique instance identifier. Default: 1

Returns: Lib::Pepper::Instance object

Throws: Exception on failure

getHandle()

Returns the underlying C handle for this instance.

my $handle = $instance->getHandle();

Returns: Integer handle value

isConfigured()

Returns true if the instance has been configured with a callback.

if($instance->isConfigured()) {
    # Ready to perform operations
}

Returns: Boolean

configure(%params)

Configures the instance with a callback and connection options. Must be called before performing any operations.

$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,
        iPosNumber     => 1,
    },
    userdata => { custom => 'data' },  # Optional
);

Parameters:

callback (required)

Code reference that will be called for events during operations. Receives 6 parameters: event, option, instanceHandle, outputOptions, inputOptions, userData

options (optional)

Hashref of configuration options. Common options:

- sHostName: Terminal address (e.g., '192.168.1.100:20007') - iLanguageValue: Display language (PEP_LANGUAGE_*) - iPosNumber: POS terminal number

userdata (optional)

Any Perl data structure to pass to callback

Returns: Output options as Lib::Pepper::OptionList object (or undef)

Throws: Exception on failure

openConnection(%params)

Opens a connection to the payment terminal. Must be called after configure() and before any transaction operations.

my $result = $instance->openConnection(
    options => {
        # Optional connection-specific parameters
    },
);

Parameters:

options (optional)

Hashref of connection options (terminal-specific parameters)

Returns: Hashref with operation_handle, status, and output

Throws: Exception on failure

closeConnection(%params)

Closes the connection to the payment terminal. Should be called when finished with terminal operations.

my $result = $instance->closeConnection(
    options => {
        # Optional disconnection-specific parameters
    },
);

Parameters:

options (optional)

Hashref of disconnection options (terminal-specific parameters)

Returns: Hashref with operation_handle, status, and output

Throws: Exception on failure

prepareOperation($operation, $inputOptions)

Executes the "prepare" step of the 4-step operation workflow.

my ($opHandle, $output) = $instance->prepareOperation(
    PEP_OPERATION_TRANSACTION,
    $inputOptions
);

Parameters:

$operation

Operation type constant (e.g., PEP_OPERATION_TRANSACTION)

$inputOptions

Lib::Pepper::OptionList object with operation parameters (optional)

Returns: List of (operation_handle, output_options)

Throws: Exception on failure

startOperation($operation, $inputOptions)

Executes the "start" step of the 4-step operation workflow.

my ($opHandle, $output) = $instance->startOperation(
    PEP_OPERATION_TRANSACTION,
    $inputOptions
);

See prepareOperation() for parameter details.

executeOperation($operation, $inputOptions)

Executes the "execute" step of the 4-step operation workflow.

my ($opHandle, $output) = $instance->executeOperation(
    PEP_OPERATION_TRANSACTION,
    $inputOptions
);

See prepareOperation() for parameter details.

finalizeOperation($operation, $inputOptions)

Executes the "finalize" step of the 4-step operation workflow.

my ($opHandle, $output) = $instance->finalizeOperation(
    PEP_OPERATION_TRANSACTION,
    $inputOptions
);

See prepareOperation() for parameter details.

operationStatus($operationHandle, $waitForCompletion)

Checks the status of an operation.

my $status = $instance->operationStatus($opHandle, 1);

Parameters:

$operationHandle

Operation handle returned from operation methods

$waitForCompletion

Boolean: 1 to wait for completion, 0 to return immediately

Returns: Status boolean (1 = complete, 0 = in progress)

Throws: Exception on failure

transaction(%params)

High-level method that performs a complete payment transaction. Executes the full 4-step workflow automatically.

my $result = $instance->transaction(
    transaction_type => PEP_TRANSACTION_TYPE_GOODS_PAYMENT,
    amount          => 10_050,      # Amount in cents
    currency        => PEP_CURRENCY_EUR,
    options         => { ... },     # Additional options (optional)
);

print "Status: $result->{status}\n";
my $outputData = $result->{output}->toHashref();

Parameters:

transaction_type (optional)

Transaction type constant. Default: PEP_TRANSACTION_TYPE_GOODS_PAYMENT

amount (required)

Transaction amount in smallest currency unit (cents for EUR/USD)

currency (optional)

Currency constant. Default: PEP_CURRENCY_EUR

options (optional)

Hashref of additional transaction options

Returns: Hashref with keys:

operation_handle

Final operation handle

status

Operation completion status (boolean) - indicates the API call completed successfully.

WARNING: This does NOT indicate payment authorization! See below.

output

Output options as Lib::Pepper::OptionList object

CRITICAL: Checking Payment Authorization

The status return value indicates whether the API call completed successfully, NOT whether the payment was authorized. An aborted or declined payment will still return status => 1 because the API call itself succeeded.

To check if a payment was actually authorized, you MUST check the transaction result in the output data:

my $outputData = $result->{output}->toHashref();
my $transactionResult = $outputData->{iTransactionResultValue} // -999;

if($transactionResult == 0) {
    # Payment was AUTHORIZED - money will be charged
    print "✓ Payment Authorized\n";
    print "Auth Code: $outputData->{sAuthorizationNumberString}\n";
    print "Amount: ", $outputData->{iAmount} / 100, "\n";
} else {
    # Payment FAILED/DECLINED/ABORTED - no money charged
    print "✗ Payment Failed\n";
    print "Reason: $outputData->{sTransactionText}\n";
}

Key Fields:

iTransactionResultValue

Payment authorization status:

0  = Payment authorized (money will be charged)
-1 = Payment declined/aborted (no money charged)

iFunctionResultValue

API call status (0 = API call succeeded). Do NOT use this to check payment success!

sTransactionText

Human-readable transaction status (e.g., "abort via timeout or abort-key")

sAuthorizationNumberString

Authorization code (empty if payment not authorized)

iAmount

Actual amount charged (0 if payment not authorized)

Common Mistake:

# WRONG - checks if API call succeeded, not if payment authorized!
if($result->{status} || $outputData->{iFunctionResultValue} == 0) {
    print "Payment successful\n";  # FALSE! May be declined/aborted!
}

# CORRECT - checks if payment was actually authorized
if($outputData->{iTransactionResultValue} == 0) {
    print "Payment authorized\n";
}

Throws: Exception on failure

settlement(%params)

High-level method that performs a settlement operation. Executes the full 4-step workflow automatically.

my $result = $instance->settlement(
    options => { ... },  # Settlement options (optional)
);

Parameters:

options (optional)

Hashref of settlement options (e.g., terminal-specific settlement parameters)

Returns: Hashref with same structure as transaction()

Throws: Exception on failure

utility(%params)

Executes a utility operation (synchronous).

my $output = $instance->utility(
    options => {
        # Terminal-specific utility parameters
    },
);

Parameters:

options (optional)

Hashref of utility operation options

Returns: Output options as Lib::Pepper::OptionList object (or undef)

Throws: Exception on failure

auxiliary(%params)

Executes an auxiliary operation (asynchronous).

my ($opHandle, $output) = $instance->auxiliary(
    options => {
        # Terminal-specific auxiliary parameters
    },
);

Parameters:

options (optional)

Hashref of auxiliary operation options

Returns: List of (operation_handle, output_options)

Throws: Exception on failure

WORKFLOW

The Pepper library uses a 4-step workflow for asynchronous operations:

1. Prepare: Validates parameters and prepares the operation 2. Start: Initiates communication with the terminal 3. Execute: Performs the main operation 4. Finalize: Completes the operation and retrieves results

For convenience, the transaction() and settlement() methods execute all 4 steps automatically.

EXAMPLE: MANUAL 4-STEP WORKFLOW

# Create and configure instance
my $instance = Lib::Pepper::Instance->new(
    terminal_type => PEP_TERMINAL_TYPE_GENERIC_ZVT,
);

$instance->configure(
    callback => \&myCallback,
    options  => { sHostName => '192.168.1.100:20007' },
);

# Build options
my $options = Lib::Pepper::OptionList->fromHashref({
    iTransactionType => PEP_TRANSACTION_TYPE_GOODS_PAYMENT,
    iAmount          => 5000,  # 50.00 EUR
    iCurrency        => PEP_CURRENCY_EUR,
});

# Execute 4-step workflow manually
my ($op1, $out1) = $instance->prepareOperation(PEP_OPERATION_TRANSACTION, $options);
my ($op2, $out2) = $instance->startOperation(PEP_OPERATION_TRANSACTION, $options);
my ($op3, $out3) = $instance->executeOperation(PEP_OPERATION_TRANSACTION, $options);
my ($op4, $out4) = $instance->finalizeOperation(PEP_OPERATION_TRANSACTION, $options);

# Wait for completion
my $status = $instance->operationStatus($op4, 1);

if($status) {
    print "Transaction completed successfully\n";
    my $result = $out4->toHashref();
    print "Result code: $result->{iResultCode}\n";
}

CLEANUP

Instance handles are automatically freed when the object is destroyed. However, for explicit cleanup:

$instance = undef;  # Calls DESTROY, frees handle

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.

SEE ALSO

Lib::Pepper, Lib::Pepper::OptionList, Lib::Pepper::Constants, Lib::Pepper::Exception

AUTHOR

Rene Schickbauer, <cavac@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2025 by Rene Schickbauer

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.

cpanm Lib::Pepper

perl -MCPAN -e shell
install Lib::Pepper