API: REST (JSON)

C# ASP.NET Example Code Set


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 Authorization Update
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

  1. Move the contents of this directory into a location in your webservers root directory
  2. Edit Web.Config in your IDE or text editor to setup the configuration
  3. Access this index page, on your webserver, through a web browser
  4. Select a transaction type and fill in the applicable fields to process a payment
  5. You must either change target Framework to 3.5 or 4.0 or download and install AJAX ASP.NET 2.0 Extensions to use parts of this sample code (json.cs)

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 connection file 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

Code Flow GiF

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/* JIFs and CSS files that are used for display purposes only. These are not required by your integration.
/App_Code/Merchant.cs This file reads configuration data from Web.Config 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.
/App_Code/Connection.cs 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.aspx.cs This file receives the POST from the x_[transaction_type].html page, processes the POST body and then uses connection.cs to send the transaction. When the response from the transaction is received, it processes the response and displays 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.
/App_Code/Json.cs This file is responsible for converting JSON strings into and out of NameValueCollections.
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.aspx.cs. 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.aspx.cs 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.aspx.cs 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".