Integrating AgentCASH Checkout

An easy way to integrate AgentCASH payment with your web shop is via Checkout, which will take care of building forms, validating input, and securing your customers' card data. 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.

Checkout is fairly high level of integration. You can still use your own forms via upcoming AgentCASH.js feature, if it doesn't fit your use-case.

 

To see how it works, try clicking on the example below, filling in the form with one of AgentCASH test card numbers (4200000000000018 Visa or 5500000000000012 MasterCard), any three digit CVC code, any expiry date in the future, and any cardholder name.

 

 

Embedding Checkout

Integration is simple. Including the JavaScript file into your web page exposes a global object "agentcash". This object is responsible for communication with the AgentCASH platform and handling of the payment form.

 

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.

 

Example: Charge 50 €

This example shows the simplest way how to integrate the charge flow into your website. Assumed merchant currency is euro.

 

The script is included into HTML once (e.g. in <head>):

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

 

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.

<button 
data-agentcash="charge"
data-amount="50.00"
data-language="en"
data-callback-url="{callback_url}"
data-external-id="{external_id
}"
data-success-url="{success_url}"
data-failure-url="{failure_url}"
data-cancel-url="{cancel_url}">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. If the 50 € transaction is approved, AgentCASH sends a POST request to URL defined with the optional data-callback-url attribute and shows confirmation dialog to the user.

If you wish to assign a custom identifier to the payment (e.g. an order number), it is necessary to supply that in the data-external-id attribute.

Body of the POST message sent to callback URL-u contains information about the payment. In case of successful payment, the POST request body contains the following data:

{
    payment_id: "...",
external_id: "...",
type: "purchase", status: "approved", receipt_url: "http://www.agentcash.com/p/3423235", amount: "50.00", currency: "EUR",
approval_code: "123456",
card_brand: "mastercard", card_masked_pan: "654321****1234", card_cardholder_name: "Andy Jervis",
card_fingerprint: "...", created_at: "2015-08-11T12:01:33Z", signature_order: "...", signature: "..." }

 

If you want to show your own page instead of default AgentCASH success/failure message, you can define URL's to those pages with optional data-success-url, data-failure-url and data-cancel-url attributes.

 

Callback signature

In order to prevent faked backend callbacks, each callback originating from the AgentCASH backend contains two security fields: signature_order and signature.

Example callback:

{
   "amount": "30.01",
   "card_cardholder_name": "Bob Gordon",
   "card_masked_pan": "550000******0012",
   "created_at": "2015-08-12T17:59:33Z",
   "currency": "EUR",
   "payment_id": "c2efcaf2-e222-405c-b9d4-6f9932d07f76",
   "receipt_url": "http://test.host/i/vXMM9letRr2NJ_Ej4K2e6w",
   "status": "approved",
   "signature_order":    "payment_id,status,receipt_url,amount,currency,card_masked_pan,card_cardholder_name,signature_order,secret",
   "signature":    "79e3fd76f392a9fe226b02646a8d2a3fb5d4f6e211298a0577f830955217a9a6d254831f1be0f4457f7649d961d4f1f93b25d9af8fad78b2f87bd3d708962b6c"
}

The signature is a SHA-512 hash of all object values ordered and joined (without delimiters) as signature_order specifies. A secret value is also included and the hash is calculated for the final string.

The above example intentionally shows fields sorted in the alphabetical order to demonstrate that their order for signature calculation is in fact specified by the signature_order field.

Secret from the example is "MeetTheFlintstones".

Therefore, values ordered according to the signature_order field from the example are:

[
   "c2efcaf2-e222-405c-b9d4-6f9932d07f76", // payment_id
   "approved", // status
   "http://test.host/i/vXMM9letRr2NJ_Ej4K2e6w", // receipt_url
   "30.01", // amount
   "EUR", // currency
   "550000******0012", // card_masked_pan
   "Bob Gordon", // card_cardholder_name
   "", // signature_order
   "MeetTheFlintstones" // secret
]

Array values are joined (without delimiters) into a string, hashed and the signature becomes:

"79e3fd76f392a9fe226b02646a8d2a3fb5d4f6e211298a0577f830955217a9a6d254831f1be0f4457f7649d961d4f1f93b25d9af8fad78b2f87bd3d708962b6c"

If the calculated signature matches the one from the request, it can be trusted. Otherwise it may not originate from a trusted source.

 

Secret

The secret is coupled with the API key used to identify the website and it can be retrieved from the AgentCASH admin UI (Webshop > API). Only merchant admins have access to this data.

The secret should not be shared publicly with anyone.

 

Choosing the UI language

The language of the pop-up dialog is deduced from the merchant's default language. However, if you want to override this default setting, you can explicitly set the card dialog language by using the optional data-language attribute. Its value should be 2-letter language code:

  • data-language="en" - sets language to English
  • "de" - German
  • "fr" - French
  • "it" - Italian
  • "es" - Spanish
  • "pt" - Portuguese
  • "ru" - Russian
  • "cs" - Czech
  • "hr" - Croatian
  • "sl" - Slovenian

 

HTTPS For Your Site

All submissions of payment info using Checkout are made via a secure HTTPS connection. However, in order to protect yourself from certain forms of man-in-the-middle attacks, we suggest that you also serve the page containing the payment form with HTTPS as well. This means that any page that a Checkout form may exist on should start with https:// rather than just http://.

 

Have more questions? Submit a request

Comments

Powered by Zendesk