Getting Started

This tutorial will show you how to:

The payment form will be created in such a way as to support both browsers that have JavaScript enabled, and those that have JavaScript disabled.

After completing this tutorial, a Transaction object should have been created on the App55 platform. See the Committing Transactions tutorial for more information on how to commit a transaction once it has been created.

Step 1: Create the HTML payment form:

The HTML form can be created using either a visual HTML editor or a web framework, or typed directly into HTML code. The following code shows an example HTML form:

<form id="create-transaction-form"
      method="POST"
      action="https://sandbox.app55.com/v1/transaction" >
    <input type="hidden" name="api_key" value="cHvG680shFTaPWhp8RHhGCSo5QbHkWxP" />
    <input type="hidden" name="next" value="https://www.example.com/app55" />
    <input type="hidden" name="transaction.amount" value="0.10" />
    <input type="hidden" name="transaction.currency" value="GBP" />

    <input type="text" name="card.address.street" placeholder="Street" /><br/>
    <input type="text" name="card.address.street2" placeholder="Line2" /><br/>
    <input type="text" name="card.address.city" placeholder="City" /><br/>
    <input type="text" name="card.address.postal_code" placeholder="Post Code" /><br/>
    <input type="text" name="card.address.country" placeholder="Country" /><br/>
    <input type="text" name="card.holder_name" placeholder="Cardholder Name" /><br/>
    <input type="text" name="card.number" placeholder="Card Number" /><br/>
    <input type="text" name="card.expiry" placeholder="MM/YYYY" /><br/>
    <input type="text" name="card.security_code" placeholder="CVV2" /><br/>

    <input type="submit" />
</form>

  • The action field should point to App55's servers.
  • The next field should point to the webpage that you wish to route the transaction-id to once it has been created. This is used when JavaScript is not enabled in the End User’s web-browser.

When the form is submitted, the card data is sent using SSL to APP55’s servers. As long as your form is set up this way, App55 will take care of all of the technical aspects for you, including encryption of the card data. You therefore don't have to worry about handling card numbers, security codes, expiration dates and other sensitive card information on your own servers.

Step 2: Initialise the App55 JavaScript library

The following procedure shows how to initialise the App55 JavaScript library on a webpage:

  1. Include the App55 JavaScript library:
    <script type=”text/javascript” src=”https://sandbox.app55.com/jsapi”></script>
    

    This code should be placed in the head tag of your page to be compatible with older web-browsers.
  2. Initialize a new gateway object with your API Key:
    <script>
    App55.debug = true;
    var gateway = new App55.Gateway("cHvG680shFTaPWhp8RHhGCSo5QbHkWxP");
    </script>
    

    Setting App55.debug to true allows debugging via a console object if console logging is available in your browser. When this is enabled, App55 will log error messages to the console.

App55 uses an API Key to uniquely identify your account. Your allocated API Key can be found on your Dashboard.

Step 3: Submit the payment form

The App55 JavaScript gateway.form function returns a collection of methods that can be used to handle HTML forms.

  • If JavaScript is enabled, then the methods intercept the form submission and instead submit via AJAX. Control is then returned to your JavaScript callback function. End User’s will therefore experience a seamless transaction with no redirects between pages.
  • If JavaScript is not enabled in the End User's web-browser then the form is first submitted directly to App55 (as specified in the form's action parameter) and then transparently redirected back to the next url that was specified in the form. This will involve a page reload.

To submit a payment form, create a transaction using the gateway.form function:

<script>
gateway.form('#create-transaction-form').createTransaction(app55ResponseHandler);
</script>

Where app55ResponseHandler is a callback method that handles the response from App55 for JavaScript enabled web-browsers. You will create this in Step 4.

gateway.createTransaction is an asynchronous call that returns immediately after it is called. app55ResponseHandler is then invoked as soon as a response is received from App55's servers.

Step 4: Send the returned transaction-id to your server

The response parameter, which is passed into the callback function, should first be inspected for errors before the transaction-id is sent. End Users should be notified if response.error contains an error. If no errors are found, JavaScript can be used to forward the full response message to your server. The message’s signature can then be verified and the transaction can be committed.

An example of inspecting a response object is shown below.

<script>
function app55ResponseHandler(response) {
    if(response.error) {
        alert(response.error.message);
    } else {
        ...
    }
}
</script>

The callback takes a response parameter, which is an object that either contains an error:

{
    "error": {
        "type": "card-error",
        "message": "Transaction Failed",
        "code": 90234
    }
}

or a Transaction object:

{
    "transaction": {
        "id": "120304132435_34345",
        "amount": "12.34",
        "currency": "GBP"
    }
}