Alviere Javascript SDK

Documentation version 0.1.0


Introduction

  • Name : Alviere Web (JS) SDK
  • Version : v0.1.0

Overview

Alviere's Web Javascript SDK leverages our financial platform on the client side, in compliance with all security and regulations.

Getting started flow

  • Step 1 - Create an authenticated web session on a secure backchannel.
  • Step 2 - Include our SDK in your Web App using the session id above.
  • Step 3 - Instantiate our SDK and create the required Service.
  • Step 4 - Use our Service, either binding or api based (details below).

Backend Authentication

Before integrating with our SDK, you need to securely generate a session. The flow is as follows:

Please see details on our API documentation

Include Web SDK

Include the SDK

The first step is to include our SDK, ideally at the very bottom of your web app.

                            (...)

                            <script src="https://api.snd.alviere.com/v1/sdk/js?session_id={{YOUR-SESSION-ID}}"></script>

                            <‍/body>
                        <‍/html>
                    

Please Note:
- You must include the session id obtained in the Backend Authentication step above.
- Make sure you use the appropriate URL depending on the mode you are in; production or sandbox.


Include Web SDK

Instantiate SDK Service

After you include our SDK, it exposes a public global variable Alviere where you can access our Controller Factory. You can then use this factory to instantiate the desired Alviere Service. Each controller corresponds to one Alviere Service.

For instance, if you wanted to instantiate our Tokenization Service, you would call the below example.

                        let service = Alviere.Factory.NewTokenizationController({});
                    

Tokenization Service

Introduction

When a payment method is added to our system through our tokenization service, we perform multiple tests before encrypting and storing the card details with the highest PCI standards.

Tokenization Flow

  • Create Tokenization Controller - Using our factory and passing the configuration object
  • Bind the SDK with your Form - This allows us to take over the form submit
  • Wait for callbacks - We will trigger the provided callbacks whenever success/failure happens

Configuration Object

                            {
                                success_cb: (result: AddCardResult) => void;
                                error_cb: (error: TokenizationGatewayError) => void;
                                validation_cb: (errors: Array<TokenizationValidationError>) => void;
                                debug: {boolean};
                            }
                        

success_cb (required)
Tokenization submit success. This is a function that will receive a AddCardResult object

error_cb (required)
Tokenization submit error. This is a function that will receive a TokenizationGatewayError object

validation_cb (required)
Tokenization form validation fail. This is a function that will receive an array of TokenizationValidationError objects

debug
This, when true, will make our SDK output debug messages to console

AddCardResult Object

The result object yields information about the payment card tokenization process result.

                            {
                                token: string,
                                accepted: boolean,
                                error_code: string,
                                error_description: string,
                            }
                        

token
This is Alviere internal card Token ID. This is the token you should store on your backend and it allows you to perform PCI compliant operations on that payment card through your backend.

accepted
Payment cards are always inserted/tokenized but they might fail some preliminary checks (e.g. cvv validation).

error_code
In case the card was not accepted, this will hold the exact error reason code.

TokenizationGatewayError Object

The gateway error object yields information about request failure on the network level.

                            {
                                message: string,
                                http_code: number,
                                error_code: boolean,
                                error_description: string,
                            }
                        

message
An SDK error message.

http_code
The underlying request HTTP Status Code

error_code
The Alviere internal API specific error code (when applicable)

TokenizationValidationError Object

The Tokenization Validation object yields information about the initial form validation result.

                            {
                                message: string,
                                field_id: string,
                                field_name: string,
                            }
                        

message
An SDK validation error message.

field_id
The DOM id where the validation error was triggered

field_name
The DOM name value where the validation error was triggered

Binding the Form

The Tokenization Controller allows you to bind to any given DOM form. For that, you need to pass the DOM id to the controller. Please note that the form inputs must follow a specific contract with data attributes.

                            let tokenizer = Alviere.Factory.NewTokenizationController({});
                            tokenizer.bind("card-tokenizer").addCard();
                        

data-alviere-id="chn"
For the card holder name field

data-alviere-id="pan"
For the card number field (numeric - we will strip any dashes or spaces)

data-alviere-id="exp"
For the card expiry date (string - must be in format MM/YY)

data-alviere-id="sec"
For the card security code (numeric - must be 3 or 4 digits e.g. cvv)

data-alviere-id="mid"
This can/should be hidden field as it must have YOUR own payment method ID. This field will be stored on our servers and used for searching as well as an idempotency checking mechanism.

Full Example

The Tokenization Controller allows you to bind to any given DOM form. For that you need to pass the DOM id to the controller. Please note the form inputs must follow a specific contract with data attributes.

                            <!doctype html>
                            <html class="no-js" lang="">

                            <head>

                                <script src="https://api.snd.alviere.com/v1/sdk/js?s=1234567890qwerty"></script>
                                <script>
                                    tokenizer = Alviere.Factory.NewTokenizationController({
                                        "success_cb": function handler(result) {
                                            console.log("received from success cb: " + result.token)
                                        },
                                        "error_cb": function handler(error) {
                                            console.log("received from error cb: " + error.error_description)
                                        },
                                        "validation_cb": function handler(errors) {
                                            console.log("received from validation cb: " + errors)
                                        },
                                        "session_id": "1234567890",
                                        "debug": true,
                                    });

                                    tokenizer.bind("card-tokenizer").addCard();
                                </script>
                            </head>
                            <body>
                                <form id="card-tokenizer">
                                    <input id="name" type="text" data-alviere-id="chn" value="John Doe"><br>
                                    <input id="pan" type="text" data-alviere-id="pan" value="5280705922407691"><br>
                                    <input id="expiry" type="text" data-alviere-id="exp" value="11/22"><br>
                                    <input id="sec-code" type="text" data-alviere-id="sec" value="123"><br>
                                    <input type="hidden" data-alviere-id="mid" value="123456789abc">
                                    <input type="submit">
                                </form>
                            </body>
                            </html>
                        

Version History (Changelog)


Changelog

                                -----------------------------------------------------------------------------------------
                                Version 0.1.0 - Jan 13th, 2021
                                -----------------------------------------------------------------------------------------

                                - initial version
                            

Copyright and license

WIP