AgentCASH.js – Getting Started¶

General notes¶

This document describes AgentCASH.js, a JavaScript library that provides AgentCASH payment form functionality to frontend applications. It is intended to be a secure plug-and-play solution for webshops that do not want to go through the PCI DSS certification hassle.

Library URL¶

Test: http://dev.agentcash.net/js/agentcash.js
Live: https://www.agentcash.com/js/agentcash.js

Integration¶

General¶

Integration is simple: including the JavaScript file into the page exposes a global object: agentcash. This object is responsible for communication with the AgentCASH platform and exposing the payment form to the end user.

If the JS file is loaded with the “key” parameter, the object will be initialized automatically and no further action is needed. Otherwise, the object needs to be manually configured by sending the API key to the agentcash.configure() method.

API keys can be found in the admin: go to the “API” section under “Webshop” and generate one. Once initialized, AgentCASH.js becomes instantly available at your fingertips.

Upon initialization, AgentCASH js will look for all DOM elements that have the data-agentcash attribute set. Based on attribute’s value, different scenarios can occur and additional attributes may be expected.

Backend callback¶

When provided with the payment, a callback will be issued by AgentCASH’s backend towards an arbitrary destination. Callback data is delivered via an HTTP POST request in the JSON data format.

More info on callbacks can be found on the Callback Signature page.

Examples¶

Script initialization¶

All examples expect the library to be properly initialized. The script should be included into HTML once (e.g. in <head>):

<script src="https://www.agentcash.com/js/agentcash.js?key=<key>"></script>

The key parameter can be found in the AgentCASH admin interface.

Charge Amount (button)¶

All buttons that serve as charge flow starting points need to be marked with the recognizable data-agentcash="charge" attribute and have a valid amount in data-amount to accompany it. Merchant currency is euro.

<button data-agentcash="charge" data-amount="50.00">Buy</button>

This button instructs AgentCASH.js to charge the user 50 €.

Clicking this button opens a pop-up dialog and kicks off the charge flow within it. The user must provide their credit card data and if the 50 € transaction is approved, a confirmation dialog is shown to the user.

Providing Customer Information for Payment¶

Depending on the acquirer which will process the payment, this might be all that you need to succesfully execute a transaction.

However, some acquirers require additional information about customer to be provided with the payment. In that case, a customer object must be specified as an argument to chargeAmount method:

  <div>
      <button id="btn-id" data-agentcash="charge" data-amount="19.00">Buy</button>
  </div>

  ...

  <script type="text/javascript">
      window.onload = function() {
          document.getElementById("btn-id").addEventListener("click", function() {
              var customer = {
                  fullName: "John Doe",
                  email: "jdoe@email.com",
                  phone: "+445342234234",
                  physicalAddress: {
                      address1: "55 Regent Street",
                      address2: null,
                      city: "London",
                      postalCode: "W1J OTR",
                      state: "London",
                      country: "GB"
                  }
              };

              agentcash.chargeAmount(this, customer).done(function(invoice) {
                  console.log("Success!", invoice);
              }).fail(function(error) {
                  console.log("Failure!", error);
              });
          });
      }
  </script>

Charge Order¶

An order can be charged through a combination of HTML and JavaScript. The call-to-action button is defined in HTML and it serves as the starting point of the checkout process.

<button id="btn-id" data-agentcash="charge_order">Checkout</button>

However, since order items can be changed at any time, they must be provided when the button is clicked and a click handler is needed.

<script>
  document.getElementById("btn-id").addEventListener("click", function() {
    var button = this;
    var items = [
      {productName: "Taxi Ride", unitPriceInclTax: "100.00", quantity: 2, taxIds: [tax1.id]},
      {productName: "Juice",     unitPriceInclTax: "11.00",  quantity: 2, taxIds: [tax1.id, tax2.id]}
    ];

    var customer = {...};  // check section 5.

    // returns a Promise object with done/fail/always callbacks
    agentcash.chargeOrder(button, items, customer).done(function(invoice) {
      console.log("Success!", invoice);
    }).fail(function(error) {
      console.log("Failure!", error);
    });
  });
</script>

The click handler initiates the payment and returns control through callbacks once it’s done.

The customer object structure is predefined and given on the Customer Information page.

Authorize Amount (button)¶

All buttons that serve as the authorization flow starting points need to be marked with the recognizable data-agentcash="authorization" attribute and have a valid amount in data-amount to accompany it. Merchant currency is euro.

<button data-agentcash="authorization" data-amount="50.00">Buy</button>

This button instructs AgentCASH.js to reserve 50 € on user’s card.

Clicking this button opens a pop-up dialog and kicks off the authorization flow within it. The user must provide their credit card data and if the 50 € transaction is approved, a confirmation dialog is shown to the user.

Store Card to Vault (button)¶

All buttons that start the add to vault flow need to be marked with the recognizable data-agentcash="vault" attribute. Merchant currency is euro.

<button data-agentcash="vault">Store card</button>

This button instructs AgentCASH.js to validate the card by charging 1 €. If the transaction is approved, the card information is stored in the vault and the transaction is voided.