https://github.com/matsuuu/web-component-e2
web-component-e is a Vanilla Web Component implementation for Paytrail E2 interface.
https://github.com/matsuuu/web-component-e2
Last synced: 2 months ago
JSON representation
web-component-e is a Vanilla Web Component implementation for Paytrail E2 interface.
- Host: GitHub
- URL: https://github.com/matsuuu/web-component-e2
- Owner: Matsuuu
- License: mit
- Created: 2021-01-26T16:42:16.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2021-04-08T06:24:15.000Z (about 4 years ago)
- Last Synced: 2025-02-12T03:19:00.410Z (4 months ago)
- Homepage:
- Size: 813 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Web-Component-E2
> :exclamation: 3rd party developed Web Component library for creating payments with [Paytrail E2 Interface](https://docs.paytrail.com/payments/e2-interface/).
## Table of Contents
- [\](#web-component-e2)
- [Installation](#installation)
- [NPM](#npm)
- [CDN](#cdn)
- [Attributes](#attributes)
- [Methods](#methods)
- [Product attributes](#product-attributes)
- [Examples](#examples)
- [Setting products](#setting-products)
- [Authcode generation](#authcode-generation)
- [Generating the authcode in the front-end](#generating-the-authcode-in-the-front-end)
- [Generating the authcode in the back-end](#generating-the-authcode-in-the-back-end)
- [Form Submission](#form-submission)
- [Minimal Setup](#minimal-setup)
- [Using the required fields](#using-the-required-fields)
- [Using all fields](#using-all-fields)
- [Directing to a certain payment provider](#directing-to-a-certain-payment-provider)
- [Payment Methods](#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
web-component-e2 will be available as a NPM package and through a CDN.
Links TBA
#### NPM
```
TBA as the repository is decided upon
```
#### CDN
TBA JSDelivr or such link
## Attributes
| Attribute | Description | Validation | Required |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `merchant_authentication_hash` | Merchant Secret. Used to generate the AUTHCODE if using `calculateAuthCodeString` and calculating the code in the frontend. | | |
| `amount` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#amount-) | Float between 0.65–499999.99 (10) | X |
| `authcode` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#authcode-) | 0-9, A-Z. (64) | X |
| `expiration_for_payment_creation` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#expiration_for_payment_creation-) | ISO-8601 notation datetime with time zone | |
| `locale` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#locale-) | fi\*FI, sv_SE, and en_US | |
| `merchant_id` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#merchant_id-) | Numeric string. (11) | X |
| `msg_settlement_payer` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#msg_settlement_payer-) | Unicode alphabets and ()[]{}\*+-\_,.\"' | |
| `msg_ui_merchant_panel` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#msg_ui_merchant_panel-) | Unicode alphabets and ()[]{}\*+-\_,.\"' | |
| `msg_ui_payment_method` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#msg_ui_payment_method-) | Unicode alphabets and ()[]{}\*+-\_,.\"' | |
| `order_number` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#order_number-) If no order number is provided, one will be generated. | 0-9, a-z, A-Z and ()[]{}\*+-\_, | X |
| `params_in` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#params_in-) | 0-9, A-Z, [],\_. (4096) | X |
| `params_out` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#params_out-) | 0-9, A-Z, [],\_. (255) | X |
| `payer_company_name` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#payer_company_name-) | Unicode alphabets and ()[]{}_+-\_,:&!?@#\$£=_;~/\"'. | |
| `payer_person_addr_country` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#payer_person_addr_country-) | a-z, A-Z. (2) | |
| `payer_person_addr_postal_code` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#payer_person_addr_postal_code-) | 0-9, a-z, A-Z. (16) | |
| `payer_person_addr_street` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#payer_person_addr_street-) | Unicode alphabets | |
| `payer_person_addr_town` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#payer_person_addr_town-) | Unicode alphabets and ()[]{}_+-\_,:&!?@#\$£=_;~/\"' | |
| `payer_person_email` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#payer_person_email-) | [email protected], max length for example is 64. (255) | |
| `payer_person_firstname` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#payer_person_firstname-) | Unicode alphabets and ()[]{}_+-\_,:&!?@#\$£=_;~/\"' | |
| `payer_person_lastname` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#payer_person_lastname-) | Unicode alphabets and ()[]{}_+-\_,:&!?@#\$£=_;~/\"' | |
| `payer_person_phone` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#payer_person_phone-) | 0-9, +-. (64) | |
| `payment_methods` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#payment_methods-) | 0-9 and , (64) | |
| `reference_number` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#reference_number-) | Alphanumeric, either numeric value complying Finnish reference number standard or numeric Finnish reference number in international RF format (e.g. 1232 or RF111232). (20) | |
| `url_cancel` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#url_cancel-) | Valid URL including http(s). URLs that do not include any dots (e.g. http://localhost) are currently not supported. (2048) | X |
| `url_notify` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#url_notify-) | Valid URL including http(s). URLs that do not include any dots (e.g. http://localhost) are currently not supported. (2048) | |
| `url_success` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#url_success-) | Valid URL including http(s). URLs that do not include any dots (e.g. http://localhost) are currently not supported. (2048) | X |
| `vat_is_included` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#vat_is_included-) | 0, 1. (1) | |
## Methods
| Method | Type | Description |
| ------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `addProducts` | `(products: Product or Array): void` | Add product(s) to the transaction. Product fields must match the [fields in the documentation](https://docs.paytrail.com/payments/e2-interface/fields/#product-information) |
| `calculateAuthCodeString` | `(): void` | Calculates the AUTHCODE string, encrypting it and appending it into the AUTHCODE input field. Assumes that a `merchant_authentication_hash` is provided. |
| `getAuthCodeString` | `(): string` | Generates the AUTHCODE string needed for calculating the AUTHCODE hash. Doesn't append a `merchant_authentication_hash`, instead assumes that the given string is passed to another API and that said API appends the `merchant_authentication_hash` before encrypting the data |
| `setAuthCode` | `(authcode): string` | Sets the authcode into the corresponding input field. Use this if you calculate the authcode in the backend and want to append it as a reaction to e.g. a fetch request. |
| `getProducts` | `(): Array` | Returns a Array of Products set into the form |
| `removeProduct` | `(product: Product): void` | Remove a product from the form |
| `removeProductAtIndex` | `(index: any): void` | Remove a product from the form given a array index |
| `setProducts` | `(products: any): void` | Set the products in the form, overwriting the current products |
| `submit` | `(): void` | Submit the Paytrail form manually |
## Product attributes
| Attribute | Description | Validation | Required |
| -------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | --------- |
| `item_title[N]` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#item_titlen-) | Unicode alphabets and ()[]{}_+-\_,:&!?@#\$£=_;~/\"'. | X |
| `item_id[N]` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#item_idn) | 0-9. (16) | |
| `item_quantity[N]` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#item_quantityn) | Floating point number. (10) | |
| `item_unit_price[N]` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#item_unit_pricen-) | Floating point number. between –499 999.99 – 499 999.99. (10) | X |
| `item_vat_percent[N]` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#item_vat_percentn-) | Floating point number. between 0-100. (10) | X |
| `item_discount_percent[N]` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#item_discount_percentn) | Floating point number. (10) | |
| `item_type[N]` | [Paytrail Documentation](https://docs.paytrail.com/payments/e2-interface/fields/#item_typen) | 1, 2, and 3. (1) | |
## 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 ``.
- `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:
```js
document.querySelector('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.
```js
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.
```js
this.querySelector("web-component-e2").addEventListener("paytrail-submit", handleSubmit);
async handleSubmit() {
const authCodeString = this.paytrailField.getAuthCodeString();
const response = await fetch("http://localhost:3000/authcode", {
method: "POST",
headers: {"Content-Type": "application/json"},
body: JSON.stringify({authCodeString})
});
this.paytrailField.setAuthCode(response.authcode);
this.paytrailfield.submit();
}
```
In the back end, the operation of generating the code would look something like this:
```js
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.
```js
```
#### Minimal Setup
```html
Pay Here
```
#### Using the required fields
```html
Pay Here
```
#### Using all fields
```html
Pay Here
```
#### 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.
```html
```
## 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
| Name | Code |
| ----------------------- | ----- |
| Nordea | 1 |
| OsuusPankki | 2 |
| Danske Bank | 3 |
| Ålandsbanken | 5 |
| Handelsbanken | 6 |
| Paypal | 9 |
| S-Pankki | 10 |
| Klarna invoice | 11 |
| Klarna Installment | 12 |
| Jousto | 18 |
| Aktia | 50 |
| POP Pankki | 51 |
| Säästöpankki | 52 |
| Visa (Nets) | 53 |
| MasterCard (Nets) | 54 |
| Diners Club (Nets) | 55 |
| American Express (Nets) | 56 |
| MobilePay | 58 |
| Collector Bank | 60 |
| Oma Säästöpankki | 61 |