In this section we will walk you through the relatively simple tasks involved in configuring FairPay for use.

Before we begin, it should be stated that in the following sections, the files mentioned reside in the main fairpay directory.

Environment File

Global environment variables that your commands require may be set by using the environment file. The presence of this file is optional.

The format of this file is identical to Bourne shell syntax, with one VAR=value assignment per line. There are a few exceptions to the Bourne-like quality of the syntax. Exports are not needed. FairPay handles this for you, as the file is not processed by a shell. Comments may be on individual lines, and blank lines are ignored. You may not put comments after value contents. The other notable difference is that you do not need to quote your values. Any quotes included (be they single or double) will be literally interpreted as part of the value for your variable.

Configuration File

The file config controls global behaviour for FairPay's handling of all applications. The presence of this file is optional, and if it is absent or empty, default values will be used.

All available options are described in detail on the Configuration Options page. The format of this file is one option=value assignment per line. Comments may be on lines by themselves, and blank lines are ignored.

Commands File

The heart of your interaction with FairPay, the file commands controls what commands are executed by flipna. This file must be present, and configured with the list of your commands for the program set.

The syntax allows for blank and separate comment lines. You may not place comments on the same line as a command. Each command should be on a separate line, and each will be processed in order at execution.

You may use any valid command on your system, and shell metacharacters (redirects, etc.) are allowed. Please note that FairPay clears the $PATH environment variable at the beginning of its execution, so you effectively have no path unless you set one in either the main or program set environment variable files. If you do not define a path, you will need to explicitly state full paths to your commands.

There are three "magic cookies" that allow you to give your commands access to the relevant files and data associated with a FairPay transaction. Wherever these tokens appear in your commands, they will be replaced with the appropriate pathname.

• %i - This token represents the XML data file generated by FairPay. This file contains the IPN data.
• %l - This token represents the internal lock number FairPay uses for your current transaction.
• %n - This token represents a unique ID that is used by both fairpay_sql_populate and any of your other applications and commands in your command list. The ID that this token will expand to is the value for which you would search for in the flt_id field within the database tables. You may alto use this ID to create transaction-specific temporary files between commands.

The fairpay_sql_populate program should always be called with -x %i as arguments, as this tells the program from which data file to populate database entries.

Should you be unable to utilise the command line to pass filenames or the internal lock number to your application, an alternate method is available in the form of environment variables. These do not go in the configuration file, but instead may be accessed from within your application:

• FLIPNA_FILE - Identical to the file that %i denotes in the commands file.
• FLIPNA_LOCK_NUMBER - Identical to the number that %l denotes in the commands file.
• FLIPNA_ID - Identical to the program name that %n refers to in the commands file.