Embedded Integration

Javascript Checkout Library

Checkout.js is a JavaScript library to easily embed Payvision checkout 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 checkout layout with your own styles.

Setup

⚠ Please note HTTPS protocol is required

Install NPM package

Install Payvision Checkout NPM package from Payvision NPM repository

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

# with yarn
yarn add @payvision/checkout-library

Payvision CDN

Alternatively, Checkout library is also available from Payvision CDN repository

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

Use of library

1. Create a checkout

Request a checkoutId via API. The checkoutId will be valid for the next 30 minutes.

POST https://stagconnect.acehubpaymentservices.com/Gateway/v3/Checkouts
{
  "header": {
    "businessId": "{{YOUR_BUSINESS_ID}}"
  },
  "body": {
    "transaction": {
        "storeId":"{{YOUR_STORE_ID}}",
        "authorizationMode":"payment",
        "amount":1,
        "currencyCode": "EUR",
        "trackingCode": "{{UNIQUE_ID}}"
    },
    "checkout":{
        "brandIds": [1010,1020,3010],
        "returnUrl": "{{REDIRECTION_URL}}"
    }
  }
}
{
    "result": 2,
    "description": "Pending",
    "header": {
        "requestTimestamp": "2019-01-01T08:00:00Z"
    },
    "body": {
        "checkout": {
            "checkoutId": "{{CHECKOUT_ID}}",
            "redirect": {
                "method": "GET",
                "url": "https://stag.checkout-web.dta.payvision.app/checkouts/{{CHECKOUT_ID}}"
            },
            "brandIds": [
                1010,
                1020,
                3010
            ],
            "expirationTime": "2019-01-01T08:30:00Z"
        },
        "transaction": {
            "amount": 1,
            "currencyCode": "EUR",
            "authorizationMode": "PAYMENT",
            "trackingCode": "{{UNIQUE_ID}}"
        }
    }
}

2. Create the checkout form

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

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

- Import the library in your JavaScript code

import Checkout from '@payvision/checkout-library'

- Customize the checkout 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 checkout through the checkout builder tool.

const options = {
  live: 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 checkout object with parameters from above

const checkout = new Checkout('{{CHECKOUT_ID}}', 'checkout-container', options)

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

checkout.render()

3. Get the payment status

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

GET https://stagconnect.acehubpaymentservices.com/Gateway/v3/Checkouts/{{CHECKOUT_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="checkout-container"></div>
      <!-- your own html code -->
    </body>
</html>
import Checkout from '@payvision/checkout-library'
const options = {
  live: true,
  styles: {
    imageUrl: 'Logo Url',
    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 checkout = new Checkout(checkoutId, 'checkout-container', options)
checkout.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

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 Checkout

false

generalStyles

Object

Contains a set of key-value general css properties.

See example

generalStyles.fontFamily

String

Checkout font family

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

generalStyles.fontFamilyUrl

String

Font family URL

Empty (no external font loaded)

generalStyles.backgroundColor

String

Checkout iframe background color.

#f6f7fb

generalStyles.primaryThemeColor

String

Checkout primary color

#213d8f

generalStyles.accentThemeColor

String

Checkout accent color

#909ec7

generalStyles.secondaryThemeColor

String

Checkout 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 checkout iframe container

100%

iframe.height

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

Height of the checkout 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 our Live environment.

Helper methods

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

Function name

Parameters

Description

Example

show

none

Displays the checkout

checkout.show()

hide

none

Hides the checkout

checkout.hide()

render

none

Renders the checkout

checkout.render()

Checkout builder

You can configure the look and feel of the checkout using our Checkout builder tool which generates the styles css which can be included in our library.

Click here to use the Checkout builder

Once you have customized the checkout, you can simply click the share button to copy the CSS styles and include it as the options.styles in our library. See example

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

Supported languages

Checkout currently supports the following languages:

Language

Language code

Czech

cs

Danish

da

Dutch

nl

English

en

Flemish

nl-BE

French

fr

German

de

Hungarian

hu

Italian

it

Norwegian

nb

Polish

pl

Portuguese

pt

Slovak

sk

Spanish

es

Swedish

sv

Updated 2 months ago

Embedded Integration


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


Top