This set contains working example code to help you integrate your application into the payment gateway. Below are the transaction types covered in this example.
| Simple Authorize x_authorize_simple.html |
Simple authorization transaction. Includes only basic fields like Card Number, Expiry, Card Security Code, Amount, Currency, IP Address and Order & Transaction References. Requires merchant to specify Order & Transaction IDs. |
| Simple Pay x_pay_simple.html |
Simple pay (aka purchase) transaction. Includes only basic fields like Card Number, Expiry, Card Security Code, Amount, Currency, IP Address and Order & Transaction References. Requires merchant to specify Order & Transaction IDs. |
| Simple Capture x_capture_simple.html |
Captures against an existing Order. Includes the Amount and Currency as well as requiring the merchant to specify the Transaction ID for the capture and the Order ID created from the initial authorisation operation. |
| Simple Refund x_refund_simple.html |
Refunds against an existing Order. Includes the Amount and Currency as well as requiring the merchant to specify the Transaction ID for the refund and the Order ID created from the initial authorisation or pay operation. |
| Simple Void x_void_simple.html |
Voids a previous transaction. Requires the merchant to specify the Transaction ID and Order ID of the transaction to void. Includes basic fields like Transaction Reference. |
| Simple Verify x_verify_simple.html |
Performs a card verification transaction. Includes only basic fields like Card Number, Expiry, Card Security Code, Currency and Order & Transaction References. Requires merchant to specify Order & Transaction IDs. |
| Simple Initiate Browser Payment x_initiate_simple.html |
Initiates a browser payment, for example, PAYPAL. Requires you to specify the amount, currency, and the return URL (the URL to which the payer's browser is redirected on completing the payment at the payment provider's website). With PayPal, you must also specify the operation and the payment confirmation flow. |
| Simple Confirm Browser Payment x_confirm_simple.html |
Confirms a successfully initiated browser payment. Requires you to specify the amount and currency. |
| Simple Update Authorization x_update_authorization_simple.html |
Updates an existing authorization. If successful, the authorization period of the existing authorization is extended and/or the authorization amount is updated. |
| Simple Retrieve Transaction x_retrieve_transaction_simple.html |
Retrieves the details of a transaction. The order ID and transaction ID must identify the transaction you wish to retrieve the details for. |
How to Use this Example Code
- Move the contents of this directory into a location in your webservers root directory
- Edit configuration.jsp in your IDE or text editor to setup the configuration
- Access this index page, on your webserver, through a web browser
- Select a transaction type and fill in the applicable fields to process a payment
Once you have the example code successfully working, you can begin to integrate your application into the API. This example set is designed to simplify your integration requirements. In many cases, you can use the configuration and connection files with no changes. You can then customize your own receipt and customer data entry pages to match your needs. Finally, the process file can be used as a basis for your own version. You should at a minimum modify this process file to calculate field values not entered by the customer (as described in Best Practices below).
How this Example Code Works
These examples are designed to give you a working sample of all major transaction operations supported through the API. All the example code is fully commented to give you an understanding of how it works and how to use the examples with your integration. The following files and folders can be found in this example set:
| /assets/* | JavaScript and CSS files that are used for display purposes only. These are not required by your integration. |
| /configuration.jsp | This file holds configuration data for some of the sensitive fields required for your integration. These specific fields need to be stored securly in your integration and never exposed to the customer. |
| /connection.jsp | This file is reponsible for sending and receiving the transaction. It initiates the connection and also has several other functions that are useful to simplify your integration efforts. |
| /index.html | This page. Contains general info and instructions for how to use this example set. This page would never be used in your integration. |
| /process.jsp | This file receives the POST from the x_[transaction_type].html page, processes the POST body and then uses connection.jsp to send the transaction. When the response from the transaction is received, it processes the response and then includes receipt.jsp to display the result. In your integration, it would be in the equivalent file that you would calculate and set data fields that are not customer facing, and are required to process a transaction. |
| /receipt.jsp | This file displays the result of the transaction. In your integration, you would need to substitute this page's function for your own receipt page to display to the customer. |
| x_[transaction_type].html | All files starting with x_ are specific to an transaction type/operation. These HTML files contain a form field which submits a POST to process.jsp. In your integration, it would be an equivalent page that the customer enters their payment details. |
Best Practices
These examples make most transaction fields available to edit when submitting the transaction. This is intended for this example only to simplify the process. In your integration, the only fields you should ever display to the customer are those requiring the customer to enter data. All other fields should be generated in your code (process.jsp in this example) and not be available to the customer.
In line with the above, you should never use HTML hidden fields to submit data to be used in the transaction request. Instead, you should specify and set these values within your application code (i.e. process.jsp based on this example)
For more best practices and tips, make sure to read the complete list in the Integration Guidelines, located under "How to Integrate".