README
<pay-trail>
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.
_ Currently still work in progress, but a working implementation with a demo will be provided in August / September 2020 _
Installation
Pay-Trail will be available as a NPM package and through a CDN.
Links TBA
NPM
TBA When 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 | Float between 0.65–499999.99 (10) | X |
authcode |
Paytrail Documentation | 0-9, A-Z. (64) | X |
expiration_for_payment_creation |
Paytrail Documentation | ISO-8601 notation datetime with time zone | |
locale |
Paytrail Documentation | fi*FI, sv_SE, and en_US | |
merchant_id |
Paytrail Documentation | Numeric string. (11) | X |
msg_settlement_payer |
Paytrail Documentation | Unicode alphabets and ()[]{}*+-_,."' | |
msg_ui_merchant_panel |
Paytrail Documentation | Unicode alphabets and ()[]{}*+-_,."' | |
msg_ui_payment_method |
Paytrail Documentation | Unicode alphabets and ()[]{}*+-_,."' | |
order_number |
Paytrail Documentation If no order number is provided, one will be generated. | 0-9, a-z, A-Z and ()[]{}*+-_, | X |
params_in |
Paytrail Documentation | 0-9, A-Z, [],_. (4096) | X |
params_out |
Paytrail Documentation | 0-9, A-Z, [],_. (255) | X |
payer_company_name |
Paytrail Documentation | Unicode alphabets and ()[]{}+-_,:&!?@#$£=;~/"'. | |
payer_person_addr_country |
Paytrail Documentation | a-z, A-Z. (2) | |
payer_person_addr_postal_code |
Paytrail Documentation | 0-9, a-z, A-Z. (16) | |
payer_person_addr_street |
Paytrail Documentation | Unicode alphabets | |
payer_person_addr_town |
Paytrail Documentation | Unicode alphabets and ()[]{}+-_,:&!?@#$£=;~/"' | |
payer_person_email |
Paytrail Documentation | example@domain.org, max length for example is 64. (255) | |
payer_person_firstname |
Paytrail Documentation | Unicode alphabets and ()[]{}+-_,:&!?@#$£=;~/"' | |
payer_person_lastname |
Paytrail Documentation | Unicode alphabets and ()[]{}+-_,:&!?@#$£=;~/"' | |
payer_person_phone |
Paytrail Documentation | 0-9, +-. (64) | |
payment_methods |
Paytrail Documentation | 0-9 and , (64) | |
reference_number |
Paytrail Documentation | 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 | 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 | 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 | 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 | 0, 1. (1) | |
submit_button_label |
The label in the submit button | Alphanumeric value | |
background_image |
The background image used in the submit button. Can be used instead of a button_label. Will remove the label. Can be used for example with a bank logo. | URL to the image |
Methods
Method | Type | Description |
---|---|---|
addProducts |
(products: Product | Array<Product>): void |
Add product(s) to the transaction. Product fields must match the fields in the documentation |
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<Product> |
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 |
Product attributes
Attribute | Description | Validation | Required |
---|---|---|---|
item_title[N] |
Paytrail Documentation | Unicode alphabets and ()[]{}+-_,:&!?@#$£=;~/"'. | X |
item_id[N] |
Paytrail Documentation | 0-9. (16) | |
item_quantity[N] |
Paytrail Documentation | Floating point number. (10) | |
item_unit_price[N] |
Paytrail Documentation | Floating point number. between –499 999.99 – 499 999.99. (10) | X |
item_vat_percent[N] |
Paytrail Documentation | Floating point number. between 0-100. (10) | X |
item_discount_percent[N] |
Paytrail Documentation | Floating point number. (10) | |
item_type[N] |
Paytrail Documentation | 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 <pay-trail>
.
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 componentremoveProduct()
expect the exact same product, that was added as a parameter, and then removes it from the arrayremoveProductAtIndex()
removes a product with given index
The API is simply called by selecting the component from the DOM and calling them:
document.querySelector('pay-trail').addProducts(productList);
Minimal Setup
<pay-trail></pay-trail>
Using the required fields
<pay-trail
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"
submit_button_label="Pay here"
></pay-trail>
Using all fields
<pay-trail
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"
submit_button_label="Pay here"
></pay-trail>
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.
<pay-trail
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"
background_image="my_bank_icon_url"
></pay-trail>
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 |