Skip to main content
knowledgecenter.avangate.com

API client-side encryption

Overview

Encrypt sensitive payment data before sending it to Avangate for orders placed via API starting with version 3.0.

Avangate provides a JavaScript library to encrypt sensitive payment information. Client-side encryption uses the payment method's fields data structures and performs data gathering and encryption using asymmetric encryption.

Purpose

The JS library exposes methods to interact with payment method object and its assigned fields, and encrypts the details.

 

Conventions used in this documentation

  • settings.{...} - You can override default settings by passing a settings object as a parameter when initializing an instance.
  • {encrypter-instance}.getSettings() - Use the {encrypter-instance} as the placeholder for the created instance. The sequence above refers to the getSettings() method called on an encrypter instance.

Benefits

Client-side encryption:

  • Reduces the scope of your PCI DSS (Payment Card Industry Data Security Standard) compliance, the key requirement when you deal with sensitive credit/debit card information.
  • Introduces a new option to capture payments when placing orders with the Avangate API.

Availability

Contact Avangate to start using API client-side encryption.

Requirements

You're required to include the following text when using Avangate API-client side encryption and to make it visible for your customers in the ordering interface. 

 

Order processed by Avangate, authorized reseller and merchant of the products and services offered within this store. 

Traditional flow requiring PCI compliance

  1. You provide shoppers with a payment interface (form) on your website.
  2. You customers enter billing and payment information such as credit card data. 
  3. When shoppers place orders, the information goes to your servers, including the sensitive payment details. Even storing the payment details in memory, or having it pass through your system, makes you a candidate for PCI compliance.
  4. You send the order data to Avangate via an API call.

How does client-side encryption work?

Client-side encryption is based on the traditional flow, but the process changes to accommodate encrypted payment information. You still receive order information from shoppers submitting it and send it from your servers to Avangate’s, but you expose yourself to a much smaller security risk by not “touching” sensitive payment information. Scenarios in which shoppers submit encrypted payment info to your servers reduce PCI DSS compliance scope.

Resources

  1. Use an Avangate-provided JavaScript library to encrypt sensitive payment information.
  2. Contact Avangate directly to obtain your public key identifier and contents.

Flow

  1. Provide shoppers with a custom ordering interface (including a payment data form).
  2. Use Avangate’s encryption JavaScript library with your public key identifier and contents to encrypt sensitive payment information. This step happens before the payment information reaches your servers. The public key is one of an RSA pair.
  • You need to include Avangate’s JavaScript library using a script tag into the ordering interface.
  • The JS library needs your public key identifier and contents to work.
  1. Once encrypted, integrate the information into the Order object and send it to Avangate. The non-encrypted payment information never reaches your environment.
  2. The Order object reaches Avangate’s servers and we decrypt the payment information using the RSA keypair’s private key, charging the customer. Avangate has exclusive access to the private key.

Use client-side encryption

Follow these steps to use client-side encryption.

Getting started

Include this JavaScript file in your implementation and follow the examples below. You can use this JS library:

  • without a view (in the NORENDER mode)
  • with an existing HTML form (in the BIND mode)
  • use the default templates and bindings to generate a basic HTML form (the INJECT mode)

 

A sample init syntax is below. (step 2 can be performed by using the available methods as described in the sample, or by using the INJECT mode with the submit action - settings.bindings.eventSubmit - or by calling getEncryptedDetails()).

 

You can override settings / features by passing different values in the settings (as the instance's constructor parameter). 

API (methods)

The exposed methods are:

  • getSettings
  • getCurrentPaymentMethod
  • getPaymentMethods
  • getPaymentMethodCodes
  • setCurrentPaymentMethod
  • isValidPaymentMethodCode
  • getEncryptedDetails 
  • render

getSettings()

See the example for a list of settings. These settings are defined in the this JavaScript file as the defaults. The settings sent to the instance's constructor are merged with and override the defaults. Their purpose is to extend the functionality. More details are found in the settings section.

getCurrentPaymentMethod()

Returns the string code for the current payment method. Default: CC 

The available payment method codes are CC and TEST. By extending the settings.paymentMethods with other entries, you can set additional methods.

See getPaymentMethodCodes() to get a list of available payment method codes and isValidPaymentMethodCode() to check if the given payment method code can be used. 

setCurrentPaymentMethod()

Sets the current payment method. Re-renders the fields, hiding fields that are were declared by the previous payment methods and binding to / injecting fields that are defined only on the new payment method.

See getPaymentMethodCodes() to get available payment method codes and isValidPaymentMethodCode to check if the given payment method code can be used. 

isValidPaymentMethodCode()

Returns boolean values and checks if the given string is a valid / available payment method code. 

getPaymentMethodCodes()

Returns a list of payment method codes (string). Default: ['CC', 'TEST'] 

getEncryptedDetails()

Encrypts the contents and returns an object with the following structure:

  • Type string - 
  • Contents string
  • Identifier string

 

Type contains the current payment method code. Default: CC **Note:** use the TEST payment method to place test orders. TEST and CC use the same fields.

 

Contents is the encrypted representation of the current payment method's fields' values, extracted using the identifier defined in settings.bindings.elementFieldMatcher. The public key contents - as defined by settings.key.contents - is used to encrypt the values..

 

Identifier contains the public key identifier - as defined at init using settings.key.identifier.

 

Note: If not input is given, will use the current payment method's fields values as input. If a input is given, is should be set as a (json-encoded) string.

 

()

render()

If the settings.mode is set to BIND or INJECT, renders (add / hide or bind to) the fields. The pattern defined in settings.bindings.elementFieldMatcher is used to match fields. (Default: [data-formField="{field-code}"]

Settings

Settings are a collection of fields, payment methods, bindings / templates / renderer.

 

Display using the {encrypter-instance}.getSettings() method and override by passing different settings when creating an instance.

 

mode

Modes are a way of controlling fields' data-view relationship. There are three available modes:

  • NORENDER
  • INJECT
  • BIND

mode: NORENDER

Used as a library, setting data, generating the encrypted values and linking will be performed at implementation.

 

This mode will skip all rendering actions at initialization. All interaction must be performed using the public methods described in the API section.

mode: INJECT

Generates a view / form, by default in HTML.

 

 

Extending the inserted template

 

Templates and field types - There are some default templates included in the library, including ways to render the payment method switcher, action button and fields. Fields ca be string or enum, for input[type="text"] and select elements. You can define other field types (for each field item, using settings.fields.{field-code}.type) and use the settings.templates.field closure to customize the field rendering. 

 

Field data/view matching** The default matcher for form elements is [data-formField='{fieldCode}'] where _{fieldCode}_ is the field's code (ex: "HolderName"). To view all available fields use {encrypter-instance}.getCurrentPaymentMethod().getFields() or {encrypter-instance}.getSettings()['fields']. To change the field matcher, update/extend the settings.bindings.elementFieldMatcher closure. (also, when using mode:INJECT, also update/extend the settings.templates.field closure to generate the same identifier).

 

Encrypt/submit action** In mode:INJECT, will also generate the payment method switcher and the submit button. The submit button triggers the settings.bindings.eventSubmit action. Update/extend this closure in the injected settings to modify the current behavior. (currently, settings.bindings.eventSubmit will trigger the settings.bindings.alert action, passing as an argument the JSON stringified results of the encryption / packing. The settings.bindings.alert action will append to the current document body the JSON string. *Update/extend this action to clear the fields or perform other actions. (ex: page forward, an async call, etc.)* Setting settings.actions.submitButton.render: false will disable the submit button's view rendering. A manual call to {encrypter-instance}.getEncryptedDetails() must be made to get the {Type, Contents, Identifier} structure.

 

All added fields will have a class defined in settings.cssClasses.fieldItem, used to style the fields. By defining a settings.cssClasses.{another-label} identifier and extending the settings.templates.field rendering template, other identifiers can be set. 

mode: BIND

Uses a pattern to link an internal field to a view element, like an input. *Default:* set by settings.bindings.elementFieldMatcher to value '[data-formField="{fieldCode}"]'. Binding can be performed in a page with more fields that needed by the library and set in the fields / payment methods settings (those extra fields will be ignored). > Note: settings.bindings.elementFieldMatcher is a closure method used to perform field matching. By default, the HTML implementation's form fields need to have data-formField="{FormCode}" in order for the view to be bounded to the data fields. 

targetSelector

When settings.mode is set to INJECT, the settings.targetSelector is mandatory. This is used to bind to a container element in which to inject a sample form. 

fields

The default field structure is:

  • label string
  • type string 
  • minLength int 
  • maxLength int 
  • values array|object 
  • defaultValue string 
  • elementSelector string  

 

Details:

  • label is a human-readable text. When settings.mode is set to INJECT, the set value is used to fill the <label> text by the settings.templates.field template.

 

 

 

settings.actions defines auxiliary actions' configuration. Default actions set are settings.actions.switchPaymentMethod and settings.actions.submitButton.

 

The default structure is: 

  • enabled boolean 
  • render boolean 
  • className string|null 
  • elementSelector string|null 
  • label string 
  • reloadText boolean

 

Details

The enabled flag is used to mark the action's usage. When set to false, the action will be skipped. 

 

  • enabled and render are relevant when settings.mode set to INJECT or BIND
  • className is intended to be used for binding / adding an identifier. 
  • elementSelector is similar to the fields' elementSelector. If specified, will bind to that element when settings.mode is set to INJECT or BIND
  • The reloadText flag is used to override the text for the detected element. (useful when settings.mode is set to INJECT or BIND)

Bindings define templates and closures that match or perform actions: 

 

  • elementGenericMatcher is a generic element matcher. By default this uses document.querySelector with a fallback element selector. 
  • elementFieldMatcher links the form field to a field entry. Default identifier: [data-formField="{field-code}"] 
  • elementSwitchPaymentMethodMatcher matches the payment method switcher element. Default identifier: [data-formswitch] 
  • elementSubmitMatcher matches the payment method switcher element. Default identifier: [data-formSubmit] 
  • eventSubmit performs the action of encrypting and dispatching the results (the {Type, Contents, Identifier} structure) to another binding action. Default action: settings.templates.alert
  • eventSwitchPaymentMethod performs the setCurrentPaymentMethod public action, using the element's target element as a link. 
  • hideAllFields is used to hide all fields, in the render() public method's flow. 
  • hideField hides the element that is passed as input. 
  • showField displays the element that is passed as input. 
  • bindFieldToElement binds the field element to the field entry. This is left blank because it depends on your custom implementation.

 

Remember to clear the fields when performing the eventSubmit action. Because this is tied to the implementation, this needs to be extended.

  • settings.templates.field is used to create the HTML representation of the given field entry. This will wrap the element (select or input, depending on the field's type value) and return a string. Extend this to generate custom fields when settings.mode is set to INJECT.
  • settings.templates.switchPaymentMethod is used to create the HTML representation of the payment method switcher. This element will be linked to the change page event and perform the settings.actions.eventSwitchPaymentMethod action.
  • settings.templates.submit is used to create the HTML representation of the submit button. This element will be linked to the click page event and perform the settings.actions.eventSubmit action.
  • settings.templates.submit is used to create the HTML representation of the submit button. This element will be linked to the click page event and perform the settings.actions.eventSubmit action.
  • settings.templates.alert is used to dispatch the encrypted results. The input will be the (JSON-encoded string representation for the) {Type,Contents,Identifier} structure. By default, settings.templates.alert will append to the page's contents. Update this in order to perform a different dispatch actions. (For example, clearing the current fields can be used in this closure.

 

 

 

 

Order object with encrypted payment information

 


{
    "Items": [{
        "Code": "broadforest-v4",
        "Quantity": 1
    }],
    "BillingDetails": {
        "FirstName": "John",
        "LastName": "Doe",
        "Email": "john.doe@shopper.com",
        "Address": "-",
        "City": "Alba",
        "PostalCode": 15500,
        "CountryCode": "ro",
        "State": "Alba"
    },
    "PaymentDetails": {
        "Type": "ENCRYPTED_PAYMENT_DATA",
        "Currency": "usd",
        "PaymentMethod": {
            "Type": "CC",
            "Contents": "fLgtBeopKVmKuT42+Aoxa3HKx450BfcuJokPnYUPH3JNG7b8fb5VPT1hCc2IfrJ3QPItOZqC3b+jkadHiX4Bnet9nxxoQtp2IauMyt2ToObI9nr/1Rn84zLWLMUFirsx9uW/lr8WgtfMVTGU0FAXk/YmYuI2CaqW8kWsHj2U0TciyAULqVJKF+7D+rd+W/6K2TIrSNgi4LzsBRo6P+4QQorS/H8uldO9fqV7VJPD34py3IFcjY2KjDK0ia2unMgrsCpkFuHREmhap6/s5U9l2mn0lAfhe6HbCTHPhA5TuS6rMREyX5xmcfgEwx1LBMclRM+5uvIcwYrLGUrmeXH0Qq2epozzArOOsnUe8AEdPpMHrQGopcicO1gUMoxgtraTD6TimdCsdwniZzTyUeUbfcj52CWpSea/txRsNrbsxrxcSPPrxEFp6JCafmUcJOGZr/Eaj0cYTaYBsBovJDpvgVzt8ecjhq3ZUi3F3f03rm/zpJHws5gEhw6MhnNFl13gSBHxgvZjNQhPksj4YVRtYT3yfRkiQZBtnq/UaOFm11gzJjCDHtvCuwJUvx+GfhPlk8/QXXG3cHzTKSrSVCWPZAGj0mkeyqvaNJdgOIT822O9PiPMpIS4NCkMzY46DTf2/SNv2mFd7ikJiw2j8SE9FVUo8LzO+v4Nfjxu1R+3m1M=",
            "Identifier": "emberjs-hello-key-00001"
        }
    }
}