Embedded Integration

Javascript PaymentLink Library

PaymentLink.js is a JavaScript library to easily embed Payvision PaymentLink into your website. By using the library, we directly send customers sensitive data to Payvision's servers so cardholder data does not hit your server, reducing PCI compliance requirements. Additionally, you can use the library to customize the PaymentLink layout with your own styles.

Setup

⚠ Please note HTTPS protocol is required

Install NPM package

Install Payvision PaymentLink NPM package from Payvision NPM repository

# with npm package manager
npm i @payvision/paymentlink-library

# with yarn
yarn add @payvision/paymentlink-library

Payvision CDN

Alternatively, PaymentLink library is also available from Payvision CDN repository

<html>
  <head>
    <script src="https://cdn.payvision.com/paymentlink/1.0.1/paymentlink-library.js"></script>
    <!-- your head definitions -->
  </head>
  <body>
    <!-- your own html code -->
    <div id="paymentlink-container"></div>
    <!-- your own html code -->
  </body>
  <script>
    const options = {...}
    const paymentLink = new PaymentLink(
      "{{LINK_ID}}",
      "paymentlink-container",
      options
    )
    paymentLink.render()
  </script>
</html>

Use of library

1. Create a PaymentLink

Request a linkId via API.

POST https://stagconnect.acehubpaymentservices.com/Gateway/v3/Paymentlinks
{
  "header": {
    "businessId": "{{YOUR_BUSINESS_D}}"
  },
  "body": {
    "transaction": {
        "amount":1,
        "currencyCode": "EUR",
        "authorizationMode":"payment",
        "trackingCode": "{{UNIQUE_ID}}"
    },
    "link":{
        "duration": "P2D",
        "brandIds": [1010,1020,3010],
        "returnUrl": "{{REDIRECTION_URL}}"
    }
  }
}
{
    "result": 0,
    "description": "Success",
    "header": {
        "requestTimestamp": "2019-01-01T08:00:00Z"
    },
    "body": {
        "link": {
            "linkId": "{{LINK_ID}}",
            "redirect": {
                "method": "GET",
                "url": "https://stag.checkout-web.dta.payvision.app/paymentlinks/{{LINK_ID}}"
            },
            "brandIds": [
                1010,
                1020,
                3010
            ],
            "expirationTime": "2019-01-01T08:30:00Z"
        },
        "transaction": {
            "amount": 1,
            "currencyCode": "EUR",
            "authorizationMode": "PAYMENT",
            "trackingCode": "{{UNIQUE_ID}}"
        }
    }
}

2. Create the PaymentLink form

- Add an HTML element as container for the PaymentLink. The container id will be used to embed the PaymentLink using the library

<div id="paymentlink-container"></div>

- Import the library in your JavaScript code

import PaymentLink from '@payvision/paymentlink-library'

- Customize the PaymentLink layout using the options JavaScript object or keep default options. Please note this parameter is not required (default options).
You can also configure the look and feel of the PaymentLink through the PaymentLink builder tool.

const options = {
  live: true,
  showDeclineButton: true,
  styles: {
    imageUrl: 'Logo Url',
    autoHeight: false,
    generalStyles: {
      backgroundColor: '#f6f7fb',
      fontFamily: 'Source Sans Pro',
      fontFamilyUrl: 'Font family url',
      primaryThemeColor: '#213d8f',
      accentThemeColor: '#909ec7',
      secondaryThemeColor: '#909ec7',
      infoThemeColor: '#1db9de',
      warningThemeColor: '#fec61f',
      errorThemeColor: '#e6493a',
      successThemeColor: '#35ba6d',
    },
    formStyles: {
      backgroundFormColor: '#ffffff',
      backgroundFormContainerColor: '#ffffff',
      fontSize: '14px',
      borderWidth: '1px',
      borderRadius: '2px',
    },
    paymentButtonStyles: {
      fontSize: '16px',
      borderWidth: '1px',
      borderRadius: '2px',
      fontColor: '#ffffff',
      backgroundColor: '#8ec03f',
      borderColor: '#8ec03f',
    },
    iframe: {
      width: '100%',
      height: '780px',
    },
  },
}

- Create a PaymentLink object with parameters from above

const paymentLink = new PaymentLink('{{LINK_ID}}', 'paymentlink-container', options)

- Use render method to display the PaymentLink in the container HTML element

paymentLink.render()

3. Get the payment status

Once the form is sent, our system redirects to the returnUrl (previously sent on the creation request) with linkId in query params, ready to get the status of the PaymentLink via API.
Example redirects to merchant returnUrl specified when creating the PaymentLink: MERCHANT_RETURN_URL?linkId={{LINK_ID}}&id={{PAYMENT_ID}}

GET https://stagconnect.acehubpaymentservices.com/Gateway/v3/Paymentlinks/{{LINK_ID}}?businessId={{BUSINESS_ID}}
{
    "result": 0,
    "description": "Completed",
    "header": {
        "requestTimestamp": "2019-01-01T08:02:00Z"
    },
    "body": {
        "payments": [
            {
                "result": 0,
                "description": "Ok",
                "header": {
                    "requestTimestamp": "2019-01-01T08:01:00Z",
                    "requestCode": "100.379b4d50-5150-4b8b-a51b-0a22e347a18f"
                },
                "body": {
                    "card": {
                        "approvalCode": "648786",
                        "cvvResult": "U",
                        "avsResult": "S",
                        "expiryMonth": "12",
                        "expiryYear": "2030",
                        "firstSixDigits": "411111",
                        "holderName": "John Doe",
                        "lastFourDigits": "1111"
                    },
                    "transaction": {
                        "amount": 1,
                        "brandId": 1010,
                        "currencyCode": "EUR",
                        "action": "payment",
                        "id": "{{PAYMENT_ID}}",
                        "trackingCode": "{{UNIQUE_ID}}"
                    }
                }
            }
        ]
    }
}

Example

<!DOCTYPE html>
<html>
    <head>
        <!-- your head definitions -->
    </head>
    <body>
      <!-- your own html code -->
      <div id="paymentlink-container"></div>
      <!-- your own html code -->
    </body>
</html>
import Checkout from '@payvision/paymentlink-library'
const options = {
  live: true,
  styles: {
    imageUrl: 'Logo Url',
    autoHeight: false,
    generalStyles: {
      backgroundColor: '#f6f7fb',
      fontFamily: 'Source Sans Pro',
      primaryThemeColor: '#213d8f',
      accentThemeColor: '#909ec7',
      secondaryThemeColor: '#909ec7',
      infoThemeColor: '#1db9de',
      warningThemeColor: '#fec61f',
      errorThemeColor: '#e6493a',
      successThemeColor: '#35ba6d',
    },
    formStyles: {
      backgroundFormColor: '#ffffff',
      backgroundFormContainerColor: '#ffffff',
      fontSize: '14px',
      borderWidth: '1px',
      borderRadius: '2px',
    },
    paymentButtonStyles: {
      fontSize: '16px',
      borderWidth: '1px',
      borderRadius: '2px',
      fontColor: '#ffffff',
      backgroundColor: '#8ec03f',
      borderColor: '#8ec03f',
    },
    iframe: {
      width: '100%',
      height: '780px',
    },
  },
}
const paymentlink = new PaymentLink(linkId, 'paymentlink-container', options)
paymentlink.render()

Options

Options is a JSON object with customizable layout properties. Different customization options are described below

Name

Type

Description

Default

live

Boolean

The target environment:
- false: staging (default)
- true: production

False

showDeclinebutton

Boolean

Show or hide the PaymentLink decline button

True

styles

Object

Contains a set of style-related properties.

See example

imageUrl

URL

Shop Logo URL

Empty (no logo displayed)

autoHeight

Boolean

Dynamically adapts the size of the container to the size of the PaymentLink

False

generalStyles

Object

Contains a set of key-value general css properties.

See example

generalStyles.fontFamily

String

PaymentLink font family

"Source Sans Pro", "Arial", "Verdana"

generalStyles.fontFamilyUrl

String

Font family URL

Empty (no external font loaded)

generalStyles.backgroundColor

String

PaymentLink iframe background color.

#f6f7fb

generalStyles.primaryThemeColor

String

PaymentLink primary color

#213d8f

generalStyles.accentThemeColor

String

PaymentLink accent color

#909ec7

generalStyles.secondaryThemeColor

String

PaymentLink secondary color

#909ec7

generalStyles.infoThemeColor

String

Notification info color

#1db9de

generalStyles.warningThemeColor

String

Notification warning color

#fec61f

generalStyles.errorThemeColor

String

Notification error color

#e6493a

generalStyles.successThemeColor

String

Notification success color

#35ba6

formStyles

Object

Contains a set of key-value of form css properties.

See example

formStyles.backgroundFormColor

String

Form background color

#ffffff

formStyles.backgroundFormC ontainerColor

String

Form font color

#ffffff

formStyles.fontSize

em, ex, %, px, cm, mm, in, pt, pc

Form font size

14px

formStyles.borderWidth

em, ex, %, px, cm, mm, in, pt, pc

Form border width

1px

formStyles.borderRadius

em, ex, %, px, cm, mm, in, pt, pc

Form border radius

2px

paymentButtonStyles

Object

Payment button css properties object

See example

paymentButtonStyles.fontColot

String

Pay button font color

#ffffff

paymentButtonStyles.backgroundColor

String

Pay button background color

#8ec03f

paymentButtonStyles.borderColor

String

Pay button border color

#8ec03f

paymentButtonStyles.fontSize

em, ex, %, px, cm, mm, in, pt, pc

Pay button font size

16px

paymentButtonStyles.borderWidth

em, ex, %, px, cm, mm, in, pt, pc

Pay button border width

1px

paymentButtonStyles.borderRadius

em, ex, %, px, cm, mm, in, pt, pc

Pay button border radius

2px

iframe

Object

Iframe css properties

See example

iframe.width

em, ex, %, px, cm, mm, in, pt, pc

Width of the PaymentLink iframe container

100%

iframe.height

em, ex, %, px, cm, mm, in, pt, pc

Height of the PaymentLink iframe container

780px

Environments

By default, the library targets to our Staging environment(option.live is false). This mode is useful for development purposes.

When you transition to our Live environment , you will need to set option.live to true in the library to target to our Live environment.

Helper methods

PaymentLink.js provides the following helper methods to manipulate the PaymentLink UI

Function name

Parameters

Description

Example

show

none

Displays the PaymentLink

paymentLink.show()

hide

none

Hides the PaymentLink

paymentLink.hide()

render

none

Renders the PaymentLink

paymentLink.render()

Supported browsers

The library supports the latest two versions of the following browsers

IE/Edge

Firefox

Chrome

Safari

iOS

IE / EdgeIE / EdgeFirefoxFirefoxChromeChromeSafariSafariiOS SafariiOS Safari

IE11, Edge

last 2 versions

last 2 versions

last 2 versions

last 2 versions