@paytrail/web-component-e2 v1.0.1

:exclamation: 3rd party developed Web Component library for creating payments with Paytrail E2 Interface.

Table of Contents

• \
  • Installation
    • NPM
    • CDN
  • Attributes
  • Methods
  • Product attributes
  • Examples
    • Setting products
    • Authcode generation
      • Generating the authcode in the front-end
      • Generating the authcode in the back-end
    • Form Submission
      • Minimal Setup
      • Using the required fields
      • Using all fields
      • Directing to a certain payment provider
  • Payment Methods

Table of contents generated with markdown-toc

Easy to use plug-and-play Web Component for Paytrail integrations.

Makes use of the E2 Payments API and eases the process of creating a Paytrail Payment gateway.

Extremely easy to set up. Uses the testing credentials, if none are probided, so you can easily get into demoing.

Installation

paytrail-web-component-e2 will be available as a NPM package and through a CDN.

NPM

npm install @paytrail/web-component-e2

CDN

<script src="https://unpkg.com/@paytrail/web-component-e2"></script>

Usage

Setup examples can be found in the setup region of the README.

Example use cases for the generation of auth codes and handling products can be found in the examples region of the README.

For the latest information and instructions, see the Official Paytrail Documentation.

Attributes

Methods

Product attributes

Examples

Setting products

Products are not set through HTML attributes, like everything else is within this component. Instead products are added using the API of <paytrail-web-component-e2>.

• addProducts() adds the given product(s) into the existing product array, and created the input fields for it.
• getProducts() returns an array with all of the products set in the component
• removeProduct() expect the exact same product, that was added as a parameter, and then removes it from the array
• removeProductAtIndex() removes a product with given index

The API is simply called by selecting the component from the DOM and calling them:

document.querySelector('paytrail-web-component-e2').addProducts(productList);

Authcode generation

The authcode can be generated in two ways:

Generating the authcode in the front-end

If you want to generate the authcode in the frontend, you can call calculateAuthCodeString(), which will use the merchant_authentication_hash provided to generate a authentication code. The function will return a promise, you can await for the generation to finish, and then submit the form manually.

async handleSubmit() {
    await this.paytrailField.calculateAuthCodeString();
    this.paytrailField.submit();
}

Generating the authcode in the frontend is not advisable, since you will be exposing your merchant_authentication_hash to the public.

Generating the authcode in the back-end

Another way of generating the authcode is by getting the authcode string (a string of values, seperated by pipes (|), and passing it to the backend.

const paytrailComponent = document.querySelector("paytrail-web-component-e2");

function handleSubmit() {
    const authCodeString = paytrailComponent.getAuthCodeString();
    const formData = new FormData();
    formData.append('authCodeString', authCodeString);
    fetch('http://localhost:3000/authcode', {
        method: 'POST',
        body: formData,
    })
        .then(res => res.text())
        .then(res => {
            paytrailComponent.setAuthCode(res);
            paytrailComponent.submit();
        });
}

paytrailComponent.addEventListener('paytrail-submit', handleSubmit);

In the back end, the operation of generating the code would look something like this:

const sha256 = require("js-sha256");

calculateAuthCode(request) {
    const authCodeString = 'MY_MERCHANT_HASH' + req.body.authCodeString;
    return {authcode: sha256.hex(authCodeString).toUpperCase()};
}

Form Submission

If a authcode has been set for the component, the form submission will launch on the click of the submit button. If however not authcode has been set (for example in cases where you generate it in the backend), a paytrail-submit -event is triggered and the default of the form submit is prevented.

Minimal Setup

<paytrail-web-component-e2>
    <label>Pay Here</label>
</paytrail-web-component-e2>

Using the required fields

<paytrail-web-component-e2
    MERCHANT_ID="13466"
    URL_SUCCESS="http://www.example.com/success"
    URL_CANCEL="http://www.example.com/cancel"
    ORDER_NUMBER="123456"
    PARAMS_IN="MERCHANT_ID,URL_SUCCESS,URL_CANCEL,ORDER_NUMBER,PARAMS_IN,PARAMS_OUT,AMOUNT"
    PARAMS_OUT="PAYMENT_ID,TIMESTAMP,STATUS"
    AMOUNT="350.00"
    AUTHCODE="BBDF8997A56F97DC0A46C99C88C2EEF9D541AAD59CFF2695D0DD9AF474086D71"
>
    <label>Pay Here</label>
</paytrail-web-component-e2>

Using all fields

<paytrail-web-component-e2
    MERCHANT_ID="13466"
    URL_SUCCESS="http://www.example.com/success"
    URL_CANCEL="http://www.example.com/cancel"
    ORDER_NUMBER="123456"
    PARAMS_IN="MERCHANT_ID,URL_SUCCESS,URL_CANCEL,ORDER_NUMBER,PARAMS_IN,PARAMS_OUT,MSG_UI_MERCHANT_PANEL,URL_NOTIFY,LOCALE,REFERENCE_NUMBER,PAYMENT_METHODS,PAYER_PERSON_PHONE,PAYER_PERSON_EMAIL,PAYER_PERSON_FIRSTNAME,PAYER_PERSON_LASTNAME,PAYER_COMPANY_NAME,PAYER_PERSON_ADDR_STREET,PAYER_PERSON_ADDR_POSTAL_CODE,PAYER_PERSON_ADDR_TOWN,PAYER_PERSON_ADDR_COUNTRY,AMOUNT"
    PARAMS_OUT="ORDER_NUMBER,PAYMENT_ID,AMOUNT,CURRENCY,PAYMENT_METHOD,TIMESTAMP,STATUS"
    MSG_UI_MERCHANT_PANEL="Order 123456"
    URL_NOTIFY="http://www.example.com/notify"
    LOCALE="en_US"
    REFERENCE_NUMBER="RF111232"
    PAYMENT_METHODS="1"
    PAYER_PERSON_PHONE="01234567890"
    PAYER_PERSON_EMAIL="john.doe@example.com"
    PAYER_PERSON_FIRSTNAME="John"
    PAYER_PERSON_LASTNAME="Doe"
    PAYER_COMPANY_NAME="Test Company"
    PAYER_PERSON_ADDR_STREET="Test Street 1"
    PAYER_PERSON_ADDR_POSTAL_CODE="608009"
    PAYER_PERSON_ADDR_TOWN="Test Town"
    PAYER_PERSON_ADDR_COUNTRY="AA"
>
    <label>Pay Here</label>
</paytrail-web-component-e2>

Directing to a certain payment provider

Do direct to a payment provider, you just need to supply a single entry into the PAYMENT_METHODS -field.

By providing a background_image -property, we can make the button the selected bank's logo.

<paytrail-web-component-e2
    MERCHANT_ID="13466"
    URL_SUCCESS="http://www.example.com/success"
    URL_CANCEL="http://www.example.com/cancel"
    ORDER_NUMBER="123456"
    PARAMS_IN="MERCHANT_ID,URL_SUCCESS,URL_CANCEL,ORDER_NUMBER,PARAMS_IN,PARAMS_OUT,AMOUNT"
    PARAMS_OUT="PAYMENT_ID,TIMESTAMP,STATUS"
    AMOUNT="350.00"
    AUTHCODE="BBDF8997A56F97DC0A46C99C88C2EEF9D541AAD59CFF2695D0DD9AF474086D71"
    PAYMENT_METHODS="52"
>
    <img src="my_bank_icon_url" />
</paytrail-web-component-e2>

Payment Methods

By specifying a PAYMENT_METHODS -field, you can create buttons that go straight to the vendor's site.

The payment methods and their codes are listed below

For the most up to date list of all of the payment methods, see the official documentation