AJAX/CORS Support

Overview

The PayConex API is designed to support asynchronous methodologies, commonly referred to as AJAX. Similar to Transparent Redirect, using AJAX will ensure that the cardholder data is never transmitted back to your webservers or network, and thus may reduce the scope of your PCI compliance requirements by removing transmitted cardholder data from your environment.

In order to support AJAX requests, Bluefin’s API has been extended to support CORS (Cross-Origin Resource Sharing). This function allows pages rendered by your server to interact with the API that is hosted by Bluefin’s servers via JavaScript.

Configuration

CORS support is enabled by default on all POST requests that do not result in a redirect (see Appendix: Transparent Redirect). To ensure that your POST results in a formatted response and not a redirect, and to ensure the response is returned in a format that can be parsed by JavaScript, set the following parameters in your HTTPS POST:

Variable Name	Max	Type	Req'd	Description
disable_redirect	1	Boolean	Yes	Disabling redirect will override the success_url and decline_url settings, and force the return of transaction response in the format specified by response_format. This setting is required for performing API calls via AJAX.
response_format	5	Enumerated	Yes	In order to interpret the response using JavaScript Object Notation, you must set the response to the value of: JSON

Browser Support

Bluefin does not provide a client-side library, as there are numerous client-side libraries that facilitate the passage of POST data to a form handler, and parsing of the response. By far, the most popular such library is jQuery. Bluefin’s AJAX support has been tested to work with modern browsers that support CORS. These browsers include: IE 10+, Firefox 3.5+, Chrome 4+, Safari 4+, iOS Safari 3.2+, Opera 12.1+, Android 2.1+, Chrome for Android 42+, Firefox for Android 37+, IE Mobile 10+, Opera Mobile 12+, and UC Browser for Android 9.9+

<?php
  // Calculate the hash before rendering page.  
  // Hashed authentication is required for AJAX requests.
  // API access key should never be visible in source code.  
  // See Appendix: Using HASH for Authenticated Transactions
  $account_id = "220000000000";
  $api_accesskey = "87f519105543418daea2cb6cb9945c7f";
  $timestamp = time();
  $hash_string = $account_id.",".$api_accesskey.",".$timestamp;
  $hash_value = hash("sha256",$hash_string);
?>

<!-- jQuery -->
<!-- Source:  http://jquery.com/download/ -->
<script type="text/javascript" src="jquery-1.11.1.min.js"></script>
<script type="text/javascript">
  $( function(){
    // Listen for the form to be submitted
    $('#cc_form').on( 'submit', function( e ){
      // Preventing default should stop browser from submitting the form.
      e.preventDefault();
      // Collect all the data that is going off to Bluefin
      var request_data = {
        account_id:         "<?php echo $account_id; ?>",
        timestamp:          "<?php echo $timestamp; ?>",
        hash:               "<?php echo $hash_value; ?>",
        tender_type:        "CARD",
        transaction_type:   "STORE",
        transaction_amount: 0.00,
        response_format:    "JSON",
        disable_redirect:   1,
        card_number:        $('#cc_num').val(),
        card_expiration:    $('#expiration').val(),
        card_verification:  $('#cvv').val(),
        zip:                $('#zip').val()
      }
      // Create an AJAX HTTPS POST request to Bluefin
      $.ajax({
        url: 'https://cert-tls12.payconex.net/api/qsapi/3.8/',
        data: request_data,
        type: 'POST',
        dataType: 'json',
        success: function( response_data ){
          // If successful, parse and act based on API response
          for ( key in response_data )
          $('#result').append( '<li>' + key + ': ' + response_data[key] + '</li>' );
         },
         error: function( error ){
         // Log any error.
         console.log( "ERROR:", "Request did not work." );
         }
       });
     // Return false to once again tell the
     // browser not to submit the form.
     return false;
   });
   });
</script>