Guides

Getting Started

Load the library

First, you must add the library and its style to the page of your site where you want the payment form to appear:

📘

About security and PCI Compliance

To be PCI Compliant you must integrate PayGreenJS directly from pgjs.paygreen.fr. The scripts and style sheets cannot be included in your bundle.

1. Load the library

Add the script and stylesheet to your page. They expose the global paygreenjs. And use latest to always get the most recent release.

<!-- Production -->
<script defer src="https://pgjs.paygreen.fr/latest/paygreen.min.js"></script>
<link  href="https://pgjs.paygreen.fr/latest/paygreen.min.css" rel="stylesheet" />

Once the script has been added, the variable paygreenjs will be available everywhere.

Sandbox (testing)

Use the sandbox CDN for testing, no real payment is taken.

<script defer src="https://sb-pgjs.paygreen.fr/latest/paygreen.min.js"></script>
<link  href="https://sb-pgjs.paygreen.fr/latest/paygreen.min.css" rel="stylesheet" />

You can create a sandbox account from your production back office in order to retrieve your shop settings.

When running in sandbox, PaygreenJS prints a one-time warning in the console.

2. Add the HTML containers

PaygreenJS doesn't render a checkout layout. It mounts its widgets inside <div> elements you provide, identified by their id.

Always required

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

This is the root mount point. Without it, paygreenjs.init() throws.



Optional — Payment Methods Container

<div id="paygreen-methods-container"></div>

Mount point for Paygreen’s built-in payment method selector (clickable list of all platforms on the payment order). Omit it if you force a single paymentMethod in init().

ScenarioDo you need it?Behavior
Several payment methods and the shopper picks one on your pageYes (unless you build your own selector)PGJS renders the payment method selector.
Single payment method already set via init({ paymentMethod: '…' })No — the selector is skippedPGJS directly shows the selected payment flow.
Custom UI with paygreenjs.setPaymentMethod('…')No — you control method selectionYou handle method selection yourself.
Element missing from the pageNo hard errorPGJS does not render the selector until a payment method is set another way.

After the buyer selects a payment method, PGJS hides the selector and displays the corresponding payment flow (card fields, wallet redirect, etc.).



Required only for card-based methods (bank_card, amex, conecs)

<div id="paygreen-pan-frame"></div>
<div id="paygreen-exp-frame"></div>
<div id="paygreen-cvv-frame"></div>
<div id="paygreen-reuse-checkbox-container"></div>
<div id="paygreen-button-container"></div>

The first three host the PAN / Expiration / CVV iframes. The last one is where PaygreenJS injects the Pay button. You can omit all if you only use wallets (Swile, Bancontact, etc.).

Pay button — two options

You have two ways to trigger the payment. Pick one:

Option A — Let PaygreenJS render the button (zero code)
<div id="paygreen-button-container"></div>

PaygreenJS injects a ready-to-use Pay button inside this container, styled to match the rest of the widget. No JS required on your side.

Option B — Use your own button

Omit paygreen-button-container and call paygreenjs.submitPayment() from your own button. This is the way to go if you need full control over the button's look & feel or placement.

<button type="button" onclick="paygreenjs.submitPayment()">
  Pay
</button>

Optional — "save my card" consent

Available only if you have the option enabled and you don't manage it by your own.

<div id="paygreen-reuse-checkbox-container"></div>

Add this only if your PSP configuration allows the buyer to save their card for future use. PaygreenJS injects a hosted consent checkbox here.

⚠️ Legal requirement
In many jurisdictions (including under GDPR and payment regulations in Europe), explicit buyer consent is required before storing a payment card for future use.

If you do not include the hosted checkbox and instead manage consent programmatically using paygreenjs.updateConsent(true), you are responsible for legally collecting and recording the buyer’s consent yourself. This means you must clearly inform users that their card will be stored and obtain their explicit agreement through your own UI and consent flow.

Without this container, the hosted consent flow is silently skipped.



3. Reference — which container for which method?

Containerbank_card / amex / conecsWallets (swile, restoflash, ancv)bancontact / klarna
paygreen-container✅✅✅
paygreen-methods-containerSee note aboveSee note aboveSee note above
paygreen-pan-frame✅——
paygreen-exp-frame✅——
paygreen-cvv-frame✅——
paygreen-reuse-checkbox-containeroptional——
paygreen-button-container✅——

4. Complete starter HTML

<!doctype html>
<html>
  <head>
    <link href="https://pgjs.paygreen.fr/latest/paygreen.min.css" rel="stylesheet" />
    <script defer src="https://pgjs.paygreen.fr/latest/paygreen.min.js"></script>
  </head>
  <body>
    <form id="checkout">

      <!-- Root mount point -->
      <div id="paygreen-container"></div>

      <!-- Payment methods selector -->
      <div id="paygreen-methods-container"></div>

      <!-- Card-based methods only -->
      <div id="yourCustomDiv">
        <div id="paygreen-pan-frame"></div>
        <div id="paygreen-exp-frame"></div>
        <div id="paygreen-cvv-frame"></div>
        <div id="paygreen-reuse-checkbox-container"></div>
        <div id="paygreen-button-container"></div>
      </div>

    </form>

    <script>
      window.addEventListener('load', () => {
        paygreenjs.init({ /* ... */ });
      });
    </script>
  </body>
</html>

5. Single-page apps

PaygreenJS watches the DOM and automatically re-attaches itself if your framework recreates #paygreen-container (e.g. on a route change). You don't need to re-init — just keep the same id on the new node.

When the buyer leaves the checkout page, call paygreenjs.unmount(true) to clean up.

Updated 9 days ago