iCharge Web and Mobile Payments  iCharge™ jServ Plugin
An invisible Javascript Plugin embedded inside your payment page that securely sends transactions from the user's browser directly to the payment gateway. Keeps credit card data away from your website, avoiding the need for PCI Compliance. jServ is the Front-end Developer's choice, giving you full control over the design of your web application and keeping users on-page without redirecting to third-party sites.


The New Face of Online Payment
Features
The jServ plugin is faceless and invisible. You have full control of the design, branding and user experience.
Card details never touch your site, so your server is not at risk. No PCI Compliance issues to worry about.
Ideal for responsive web apps and white-labelled solutions.
Users stay on-page throughout the transaction. No popups, frames or redirection to a third-party site.
A pure Javascript API that peacefully coexists with any library or framework you choose without conflict or interference.
Supports simple one-off payments, AutoCharge (automated recurring charges) and Tokenization (secure card storage for future or deferred charges).
No back-end programming required for most simple e-commerce applications. Includes a powerful merchant administration back-end system to run your business 24X7 from anywhere. Track payments, make refunds, produce business reports, and more.
Callback function posts the status of every transaction back to update your back-end application if required.

Get Your jServ Test Payment Page Up And Running In 5 Minutes

  1. Download the sample jServ payment page: http://www.xilo.com/jserv/jservtestpage.htm.zip
    Unzip the file and save the page jservtestpage.htm somewhere on your hard disk. That's right, you don't need a web server for this.
  2. Open the file jservtestpage.htm in your web browser.
    Try a test payment using one of these dummy card numbers:
    VISA 4444 3333 2222 1111
    MASTERCARD 5555 5555 5555 5557
    Select any card expiry in the future.
    Enter any 3 digits for CVC.
    Enter your name and email address to receive a tax invoice in your in box.
    Click NEXT and follow the prompts to confirm the transaction.
    Your test payment should be successful and approved.
    You can print the tax invoice off the screen.
    Check your in-box - after a few minutes you should also receive an email tax invoice.
  3. Try more tests:
    • Invalid card number - change one digit of the dummy card number
    • Expired date
    • Invalid email format
    • Declined transaction - edit the page, look for hard-coded "99.00" and change to "99.51". This simulates "Insufficient Funds" condition.

That was quick and super easy! Now what?

Build Your Test Payment Page And Learn How It Works In 30 Minutes

This tutorial steps you through building your test payment page from scratch and in the process learn about all its moving parts.
The completed working page may be downloaded from here: http://www.xilo.com/jserv/jservtestpage.htm.zip
In case things don't work as expected, compare the code between your page and the completed page.

  1. Create a HTML file on your hard disk. Call it any name, eg. mytestpage.htm. Start with this basic markup:
    SELECT ALL
  2. Load the jServ plugin by copying this code into the HEAD section of your page:
    SELECT ALL
  3. Code up a credit card form in the BODY of your page as shown below:
    SELECT ALL
    The form is wrapped inside a DIV with ID "PaymentFormDiv".
    There are 7 form fields and 3 buttons used in this example, but only the NEXT button is displayed at this time.
    Generally you may use any element IDs you wish on your own page, but for this demo, stick to the IDs used in this example.
    Note the SPAN tags with display turned off following each of the form fields. These will be used later for confirmation text.
    At the bottom, another DIV named "UserMessageDiv" will be used later for displaying information back to the user.
  4. This exercise is not about CSS styling, but default styles are inconsistent across different browsers and can be unbearably ugly.
    So we'll include some light styling to give our page a more modern look.
    Place this CSS block into the HEAD section of your page:
    SELECT ALL
    Two CSS classes, "normal" and "bad" are defined for the form fields. By switching between the two classes we can highlight invalid fields.
    If you look back to the code you added in the previous step, the form fields are initially set to "normal" state.
  5. Open your test page in a browser. There are 3 selector fields and 4 text input fields, but the selectors are empty.
    Note the special class names of the selector tags: _jserv.CardType_Selector, _jserv.ExpiryMM_Selector, _jserv.ExpiryYY_Selector
    These are special jServ Helper Classes that will automatically populate the selectors with valid options when the jServ plugin is intialized.
    We now initialize the plugin by placing this script as the last statement in the BODY of your page:
    SELECT ALL
    This ensures that the initialization function is called only after the form is loaded.
    The parameter passed in the _jserv.Initialize() function is your Merchant ID. For this test page, use the Merchant ID "jservdemo" as shown. "jservdemo" is the only Merchant ID that will work when you are hosting a test page on your hard disk. When you have your own iCharge account and you are hosting on a proper web server, you should use your own Merchant ID that uniquely identifies your business.
  6. Now reload your test page. The selectors are now magically populated with valid options.
    The card type options are predefined in the jservdemo account, so that only valid card types for this merchant are available for selection.
    The card expiry options are based on the next 20 years from today.
  7. We'll now work on the other transaction parameters.
    The following HTML fragment defines the payment amount, tax, invoice number and description.
    Insert it above the "PaymentFormDiv" that contains the form.
    SELECT ALL
    Reload the page and ensure that the amounts are visible to the user when making a payment.
    The parameters are hard-coded in this example. In your own application, these values should be dynamically set by your code.

    Invoice Number is any alphanumeric reference field that you can use to tag this transaction and associate it with the customer order. A unique reference should be set by your application, but no uniqueness check is made, so it's OK to use the same hard-coded value in demo examples.
  8. Note that the NEXT button has an onClick action that calls the Next() function.
    Define the Next() function with this Javascript code, which should be inserted in the HEAD section of your page, after the line inserted in Step 2 above.
    SELECT ALL
    There seems to be a lot going on here, but it's actually quite simple.
    What this function does is to display the payment form fields for confirmation.

    For each form field:
    Copy the the user-entered value into the corresponding display span.
    Hide the form field and show the display span.
    Reset to the normal state by applying the "normal" class.
    Clear and hide UserMessageSpan.
    Hide the NEXT button and display the CONFIRM and BACK buttons.
  9. It's time to see some action. Reload your page and enter credit card details.
    Do not use a real card number - use one of the following dummy card numbers instead:
    VISA 4444 3333 2222 1111
    MASTERCARD 5555 5555 5555 5557
    Select any expiry date in the future and any 3 digits for the CVC code.
    Use your own name and email address in order to receive the tax invoice.
    Click the NEXT button.
    You should now see the confirmation screen with buttons to CONFIRM or go BACK.
  10. We'll code the action for the BACK button, which calls the function Back().
    Insert this function within the same <script> block as the Next() function in Step 8.
    SELECT ALL
    The Back() function is doing exactly the reverse of the Next() function, bringing the user back to the payment form to make changes.
    Reload the page, re-enter the credit card data, click NEXT. Then click BACK to see it in action.
    You can click back and forth between NEXT and BACK to switch between the two states.
  11. The CONFIRM button calls the Confirm() function to send the transaction to the payment gateway for processing.
    Before we get into that, here's a brief explanation of the data and control flow between your page and the gateway:

    Transactions are sent to the gateway in a Request Object package, and the transaction response is returned from the gateway in a Response Object package. Both objects are predefined in the plugin and are empty when the plugin is initialized. To submit a transaction, the Request Object must first be populated with transaction parameters on your page. Then a function called "_jserv.CardPaymentRequest.Do()" is called that sends the Request Object off to the gateway.

    When the transaction has completed processing, the gateway populates the Response Object with the transaction status. Then a callback function named "_jserv.CardPaymentResponse.Done()" is called to hand control back to your page. On your page, any code within the callback function has access to the transaction status data in the Response Object.

    The Request Object for a card payment transaction is called "_jserv.CardPaymentRequest".
    The Response Object is called "_jserv.CardPaymentResponse".
    To inspect all the elements in the Request Object and Response Object, open your browser console and enter the name of each object.
    You will see that neither object has been populated at this stage.

    Here's the code for the Confirm() function. Insert it in the same <script> block as the Next() and Back() functions.
    SELECT ALL
    Here's what this function does when CONFIRM is clicked:
    Hide the payment form fields and buttons to prevent the user from double-clicking CONFIRM and creating a duplicate transaction.
    Display a progress message to reassure the user that something is happening.
    Populate the Request Object "_jserv.CardPaymentRequest" with all the transaction parameters, both the values defined by your application and credit card values entered by the user.
    Finally, call the Card Payment Request function "_jserv.CardPaymentRequest.Do()" that picks up the Request Object and submits it to the payment gateway.

    Note how the Amount and Tax values are copied across:
    The Request Object values "_jserv.CardPaymentRequest.Amount" and "_jserv.CardPaymentRequest.Tax" must be expressed as integer cents, but they are found on your page in Dollars.Cents format. The _jserv.DollarsToCents() Helper Function performs the necessary conversion for us. There are many handy jServ Helper Functions included in the plugin for your use - details in the jServ documentation.

    Do not click CONFIRM just yet - we must first create the callback function to handle the response coming back from the gateway, which we will do in the next step.
  12. The callback function "_jserv.CardPaymentResponse.Done" must be defined in your page to handle the transaction response.
    Here's the code for this function - insert it in the same <script> block as the earlier functions.
    SELECT ALL
    Note that the special way this callback function is defined.
    For now, all we do is to display the Response Object in the browser console after the transaction is processed.
    Let's give it a try - make sure your browser console is open, reload the page, enter the card details, click NEXT, then click CONFIRM.

    If everything has been done correctly so far, here's what should happen:
    On your page, the progress message is displayed, and continues to be displayed because we haven't done anything to remove it.
    In your browser console, the Response Object is displayed. Expand the object to see the transaction status.
    The key elements to watch out for are:
    ReturnCode: 0 if there are no errors, otherwise a non-zero value as described in documentation.
    ReturnMessage: "OK" if there are no errors, otherwise a message indicating the error.
    TransactionStatus: APPROVED|DECLINED|ERROR|ONHOLD|STOPPED|UNKNOWN
    TransactionResponseCode: A code giving further details about the transaction status - details in documentation.
    BankRRN: A code assigned by the bank in acknowledgement of the transaction.
    Other elements are self-explanatory and fully described in the documentation.

    Check your mail inbox. After a few minutes, you should receive an email tax invoice for the payment.
  13. We have demonstrated how a card payment is submitted from your page directly to the payment gateway for processing and the response received back on your page. To complete the user experience, we must update the page so that the user knows the transaction result.
    We'll now change the callback function to do that instead of just pushing the Response Object to the console log.

    Replace the callback function we used in the previous step with this one:
    SELECT ALL
    Within the callback function, we examine the Response Object and compose appropriate responses to display:
    First, we assign a short name "Resp" as an alias for the full name of the Response Object _jserv.CardPaymentResponse to save typing.
    We also initialize RespText as the variable for holding the user message.

    Check if there were errors.
    ReturnCode zero means no errors, and we test TransactionStatus.
    If TransactionStatus APPROVED, we compose a suitable message to the user, making use of values picked up from the Response Object.
    If TransactionStatus DECLINED, we compose a different message to the user.
    If TransactionStatus is anything else, we compose yet another message to convey the error.

    Non-zero ReturnCode indicates error, and we just display the ReturnMessage to the user.
    There is a comment "Placeholder" where we will insert more code later.

    Reload the page and try another transaction.
    This time, you should see the TRANSACTION APPROVED message on-screen.

    If you would like test a DECLINED transaction, we have a trick to simulate that.
    In test mode only, the cent value of the transaction is returned as the TransactionResponseCode element of the Response Object.
    The two-digit TransactionResponseCode is normally used to indicate the reason why the transaction was declined.
    For example, TransactionResponseCode 51 means "Insufficient Funds".
    Edit your amount to 99.51 (Refer to Step 7), reload your page and try again.
    This time, a DECLINED message will be displayed to the user.
  14. There is a class of errors caused by invalid transaction parameters entered by the user.
    In such cases, we want to highlight the error and allow the user to make corrections and re-enter the transaction.
    Validation errors give a ReturnCode value of 2XX - where the XX indicates the error field (refer to documentation).

    We will now add some extra code that will re-display the credit card form and highlight the error field.
    Replace the "Placeholder" comment from the previous step with the following block of code.
    SELECT ALL
    A switch statement interprets the ReturnCode and highlights the field that failed validation by calling the ShowBadField() function, passing the ID of the error field.
  15. Now we'll need to define the ShowBadField() function.
    Add this function to our list of functions:
    SELECT ALL
    The Back() function we defined in Step 10 is called to re-display the credit card form.
    The DIV "PaymentFormDiv" containing the form is turned on (it was turned off when CONFIRM was clicked).
    The CSS class of the form element identified by the passed parameter is switched to "bad" (white text on red background).
    This is wrapped in an "if" statement to avoid Javascript errors in case the identified element does not exist.

    Time to test. Reload the page and create a validation error by using an invalid card number by changing the last digit of the card number, for example VISA 4444 3333 2222 1110.
    Your payment form should be presented with the card number highlighted.
  16. The final steps in this demo provide a means for the user to print the payment receipt off the page. The user can always use the browser print function to print the whole page, but that's pretty crude because they may be a lot of other content on the same page not relevant to the transaction. We want to be able to control exactly what is is printed.

    We use CSS Media Queries to control and define print content.
    Add the following CSS statements within the <style> block you added in Step 4.
    SELECT ALL
    These media query statements define two CSS classes: "print-only" and "screen-only", allowing us to control visibility of print content and display content separately.
  17. We want a receipt header only visible on the printed receipt, but not on-screen. So we define a header DIV with the CSS class "print-only". Inside this DIV, we hard-code the content to be printed at the top of the receipt, typically a title, business name, ABN and contact details.
    Place this DIV where we want the printed header to appear, in this case immediately above the block of HTML you added in Step 7.
    SELECT ALL
    Now reload your page to check that the receipt header is not visible because it is print-only.
  18. To define what content should be printed, we wrap whatever HTML we want to appear on the printed receipt inside a named DIV.
    Put the opening tag immediately above the print header DIV you added in the previous step.
    SELECT ALL

    Put the closing tag for this DIV immediately after the block of HTML you added in Step 3.
    SELECT ALL
  19. Create a PRINT button that is displayed only if there is a receipt to print:
    This button is inserted into the user message only under the conditions when ReturnCode is 0 and TransactionStatus is APPROVED.
    Locate this line of code in the callback function that you added in Step 13: RespText += Resp.CompletionMessage + "<br>";
    This is the branch where a receipt is printable. Add the following line of code immediately after:
    SELECT ALL
    Let's take a moment to unpack this statement:
    It inserts the HTML for a PRINT button only if the transaction has no errors and the payment is approved.
    With a CSS class of "screen-only", this button is visible on-screen, but not on the printed receipt.
    When clicked, it calls a jServ Helper Function _jserv.PrintReceipt(), passing the ID "PrintContainer" of the DIV that we created in step 18.
    _jserv.PrintReceipt() starts printing only the content inside the specified container and nothing else.
  20. FINAL TEST:
    Reload your page and run the test from start to finish.
    When the transaction has successfully completed, the PRINT button should be displayed.
    Click to print the receipt.
    On the printed copy, note that everything inside your PrintContainer DIV is printed except the PRINT button.

Thank you for following our jServ tutorial to the very end, but we have just scratched the surface of jServ. What next?