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:
- Your backend needs to generate a web session with Alviere.
- Then, your frontend needs to include the Alviere web SDK (via script) using the previously generated session id.
- Finally, the Alviere web sdk is ready to be instantiated and used. More details here
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/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.
Instantiate SDK Service
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 Payments Service or our Fraud Service, you would call the below example.
let service = Alviere.Factory.NewPaymentsController({});
let service = Alviere.Factory.NewFraudController();
Payments Service
Introduction
When a payment method is added to our system through our payments service, we perform multiple tests before encrypting and storing the card details with the highest PCI standards.Create Card Flow
- Create Payments 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: AddCardGatewayError) => void;
validation_cb: (errors: Array<AddCardValidationError>) => void;
debug: {boolean};
}
success_cb (required)
Add Card submit success. This is a function that will receive a AddCardResult
object
error_cb (required)
Add Card submit error. This is a function that will receive a AddCardGatewayError object
validation_cb (required)
Add Card form validation fail. This is a function that will receive an array of AddCardValidationError objects
debug
This, when true, will make our SDK output debug messages to console
AddCardResult Object
The result object yields information about the payment add card process result.
{
"card": {
"payment_method_uuid": "09f46e1f-aa02-46ec-ae6d-34946f385e3d",
"external_id": "string",
"account_uuid": "string",
"brand": "VISA",
"type": "CREDIT",
"country": "USA",
"last_4": "0000",
"status": "ACTIVE",
"status_reason": "string",
"flags": {
"load_supported": true,
"withdraw_supported": false
},
"metadata": {},
"created_at": "string",
"updated_at": "string"
},
"validation": {
"error_code": "",
"error_description": "",
"cvv_result": "M",
"avs_result": "A"
}
}
card.payment_method_uuid
This is Alviere internal card ID. This is the uuid you should store on your backend and it
allows you to perform PCI compliant operations on that payment card through your backend.
card.status
The status of the card
Allowed values: CREATED, ACTIVE, FAILED, EXPIRED, REJECTED, DELETED
card.status_reason
In case the card failed, this will hold the exact error reason.
AddCardGatewayError 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)
AddCardValidationError Object
The Add Card 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 Payments 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 payments = Alviere.Factory.NewPaymentsController({});
payments.bind("add-card-form").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 Payments 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/sdk/js?session_id={{YOUR-SESSION-ID}}"></script>
<script>
payments = Alviere.Factory.NewPaymentsController({
"success_cb": function handler(result) {
console.log("received from success cb: " + result.card.payment_method_uuid)
},
"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)
},
"debug": true,
});
payments.bind("add-card-form").addCard();
</script>
</head>
<body>
<form id="add-card-form">
<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>
Fraud Service
Introduction
When a consumer is created, the Fraud Service will ensure that the device data is collected and sent to our Fraud Provider, in order to reduce the fraud risk.Fraud Flow
- Create Fraud Controller - Using our factory
- Start the Fraud Service - This allows us to instantiate the fraud service
Full Example
<!doctype html>
<html class="no-js" lang="">
<head>
<script src="https://api.snd.alviere.com/sdk/js?session_id={{YOUR-SESSION-ID}}"></script>
<script>
fraud = Alviere.Factory.NewFraudController();
fraud.bind().start();
</script>
</head>
<body>
...
</body>
</html>
Card Issued Service
Introduction
With this controller you can trigger multiple operation on the Card Issuance module.Set Pin Flow
- Create Card Issuance Controller - Using our factory and passing the configuration object
- Bind the SDK with your Form - This allows us take over the form submit event
- Wait for callbacks - We will trigger the provided callbacks whenever success/failure happens
Configuration Object
{
success_cb: (result: SetPinResult) => void;
error_cb: (error: CardIssuanceGatewayError) => void;
validation_cb: (errors: Array<CardIssuanceValidationError>) => void;
debug: {boolean};
}
success_cb (required)
Set PIN submit success. This is a function that will receive a SetPinResult
object
error_cb (required)
Set PIN submit error. This is a function that will receive a CardIssuanceGatewayError object
validation_cb (required)
Set PIN form validation fail. This is a function that will receive an array of CardIssuanceValidationError objects
debug
This, when true, will make our SDK output debug messages to console
SetPinResult Object
The result object yields information about the Set PIN request result.
{
accepted: boolean,
error_code: string,
error_description: string,
}
accepted
If the request succeed or not
error_code
In case the request failed, this will hold the exact error reason code.
CardIssuanceGatewayError 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)
CardIssuanceValidationError Object
The Card Issuance 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 Set PIN 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 card_issuance = Alviere.Factory.NewCardIssuanceController({});
card_issuance.bind("card-set-pin-form").setPin();
data-alviere-id="pin"
For the card PIN field
data-alviere-id="pinc"
For the card PIN confirmation field
data-alviere-id="cuid"
For the card UUID
Full Example
The Set PIN 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.
<!doctype html>
<html class="no-js" lang="">
<head>
<script src="https://api.snd.alviere.com/sdk/js?session_id={{YOUR-SESSION-ID}}"></script>
<script>
cardIssuance = Alviere.Factory.NewCardIssuanceController({
"success_cb": function handler(result) {
console.log("received from success cb: " + result.accepted)
},
"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)
},
"debug": true,
});
card_issuance.bind("card-set-pin-form").setPin();
</script>
</head>
<body>
<form id="card-set-pin-form">
<input id="pin" type="text" data-alviere-id="pin" value="1234"><br>
<input id="pin-confirmation" type="text" data-alviere-id="pinc" value="1234"><br>
<input type="hidden" data-alviere-id="cuid" value="650ad655-5f91-4956-866d-764072986955">
<input type="submit">
</form>
</body>
</html>
Version History (Changelog)
Changelog
-----------------------------------------------------------------------------------------
Version 0.6.0 - Dec 28th, 2023
-----------------------------------------------------------------------------------------
- added payments add card
-----------------------------------------------------------------------------------------
Version 0.5.0 - Sep 28th, 2022
-----------------------------------------------------------------------------------------
- added card issued set pin
-----------------------------------------------------------------------------------------
Version 0.4.0 - May 16th, 2022
-----------------------------------------------------------------------------------------
- added fraud controller
-----------------------------------------------------------------------------------------
Version 0.1.0 - Jan 13th, 2021
-----------------------------------------------------------------------------------------
- initial version
- tokenization controller
Copyright and license
WIP