Skip to main content

Integrating Bizzon Checkout

Updated

An easy way to integrate Bizzon payment with your webshop is via Checkout, which will take care of building forms, validating input, and securing your customers' card data.

Checkout is a fairly high level of integration.
You can still use your own forms via the upcoming Bizzon.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 Bizzon 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

The integration is simple. The JavaScript file on your web page exposes a global object "agentcash" responsible for communication with the Bizzon 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 the 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. The assumed merchant currency is euro.

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

<script src="https://www.bizzoh.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 dialogue and kicks off the charge flow within it. The user must provide their credit card data. If the 50€ transaction is approved, Bizzon sends a POST request to URL defined with the optional data-callback-URL attribute and shows a confirmation dialogue 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.

The 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 Bizzon 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 Bizzon 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 alphabetical order to demonstrate that their order for signature calculation is in fact specified by the signature_order field.

A 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 Bizzon 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 dialogue is deduced from the merchant's default language. However, if you want to override this default setting, you can explicitly set the card dialogue 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://.

 

Related articles

Comments

0 comments

Article is closed for comments.