Seamless Integration Guide

Overview

To integrate the Payment Page in Seamless Mode in your shop, get your checkout page ready in two steps:

  1. Preparing your checkout page: Add the paymentPage.js library to your checkout page’s HTML code.

  2. Changing the background color setting in Payment Page Designer: Set the background color to transparent in Payment Page Designer.

Then use a backend-to-backend JSON workflow for the payment process.

  1. Create a payment session: You send an initial POST request with details of the transaction to the Payment Page. This POST request is secured by basic access authentication.

  2. Render the seamless payment form: Payment Page returns an initial response URL.

    • If the initial POST request is correct, use this response URL and the WPP.seamlessRender library call to render the payment form in a seamless iframe. Continue with step 3.

    • If the initial POST request is faulty, Payment Page returns an error code with a description of the problem in the response. Return to step 1.

  3. Submit the payment: The consumer fills in the payment form. Use the WPP.seamlessSubmit function to submit the payment. Ensure that the function is bound to an interactive UI element, such as a button, in your HTML code.

    • 3D Secure credit card payment automatically redirects the consumer to the authentication page, and then to a Payment Page success- or fail-redirect-url. Include the success- and fail-redirect-urls in your initial request! This page includes a JSON sample for 3D Secure credit card payment.

  4. Parse and Process the Payment Response: The payment is processed. Payment Page returns base64 encoded payment data. It is highly recommended that you parse and process this base64 encoded response to verify the payment.

First Steps

Before processing payments in Seamless Mode, you need to make a small adjustment to your checkout page’s HTML code, and change a setting in the Payment Page Designer.

1. Preparing your Checkout Page

Add the paymentPage.js library to your checkout page HTML code:

<script src="https://paymentpage-test.getneteurope.com/loader/paymentPage.js" type="text/javascript"></script>

This library lets you render the payment form as an iframe in your checkout page.

The URL included here serves only as an example. Please enter the domain of the instance received during merchant configuration.
2. Changing the Background Color Setting in Payment Page Designer

Open the Payment Page Designer to set the background color to transparent. Transparency of the card form’s background ensures a seamless appearance when it is embedded in your checkout page.

  1. Select the Payment tab and click on Colors.

    Seamless Page Designer 1
  2. In Colors, go to the Content tab and open the Content Background Color window.

    Seamless Page Designer 2
  3. Set the Content Background Color alpha value (A) to 0

    Seamless Page Designer 3
Payment-Processing Example

This is an example of a credit card 3D Secure transaction to show how to process a payment with the Payment Page in Seamless Mode. Currently, Seamless Mode supports only credit card payments. For a more payment-method-specific integration guide, go to Credit Card.

The payment-processing example is designed for the testing environment and does not use real information.

Payment processing with Payment Page in Seamless Mode deviates a little bit from the

HPP and EPP payment processing workflow:

Payment Processing with Payment Page in Seamless Mode

  1. Create a payment session (initial request).

  2. Render the Seamless payment form in your checkout page (initial response URL).

  3. Submit the payment.

  4. Highly recommended: Parse and process the payment response.

Payment Processing with HPP and EPP

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

  3. Highly recommended: Parse and process the payment response.

Setup and Test Credentials

Before you can send your first request, use the following information to set up your testing tool:

Test Credentials

URI (Endpoint)

https://paymentpage-test.getneteurope.com/api/payment/register

Username

To be determined

Password

To be determined

MAID

To be determined

Secret Key

To be determined

Test Card

Card Number

4012000300201199

Expiration Date

01/23

CVV

199

3D Verification Password

123456

1. Create a Payment Session

To create a payment session, send a POST request to the /api/payment/register endpoint, e.g. https://paymentpage-test.getneteurope.com/api/payment/register.

This is an HTTP request with two headers:

Request Headers
Content-Type: application/json
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==

The Authorization header needs to be formatted as: "Authorization"="Basic" + base64("username:password")

Create a Payment Session (Initial Request)
{
    "payment": {
        "merchant-account-id": {
            "value": "cad16b4a-abf2-450d-bcb8-1725a4cef443"
        },
        "request-id": "{{$guid}}",
        "transaction-type": "purchase",
        "requested-amount": {
            "value": 10.1,
            "currency": "EUR"
        },
        "payment-methods": {
            "payment-method": [
                {
                    "name": "creditcard"
                }
            ]
        },
        "three-d": {
            "attempt-three-d": "true"
        },
        "success-redirect-url": "https://demoshop-test.getneteurope.com/demoshop/#/success",
        "fail-redirect-url": "https://demoshop-test.getneteurope.com/demoshop/#/error",
        "cancel-redirect-url": "https://demoshop-test.getneteurope.com/demoshop/#/cancel"
    },
    "options": {
        "mode": "seamless",
        "frame-ancestor": "https://www.example.com"
    }
}
Field (JSON) Data Type Required/Optional Size Description

merchant-account-id

value

String

Required

36

A unique identifier assigned by us to every merchant account.

request-id

String

Required

150

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later. {{$guid}} serves as a placeholder for a random request-id. Allowed characters:
a - z
0 - 9
-_

transaction-type

String

Required

36

The requested transaction type.

requested-amount

value

Numeric

Required

18

The full amount that is requested/contested in a transaction. 2 decimal places allowed.
Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount. Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

Optional

15

The name of the payment method used. Set this value to creditcard.

three-d

attempt-tree-d

Boolean

Conditional

N/A

Required for 3D Secure transactions. Indicates whether 3D Secure authentication is enabled for the transaction.

success-redirect-url

String

Optional

256

The URL to which the consumer is redirected after successful payment, e.g. https://demoshop-test.getneteurope.com/demoshop/#/success

fail-redirect-url

String

Optional

256

The URL to which the consumer is redirected after successful payment, e.g. https://demoshop-test.getneteurope.com/demoshop/#/error

cancel-redirect-url

String

Optional

256

The URL to which the consumer is redirected after successful payment, e.g. https://demoshop-test.getneteurope.com/demoshop/#/cancel

options

mode

String

Required

8

Indicates which mode of payment page is used for the payment. Currently supports embedded and seamless. Use seamless in this example.

To create a payment session with Credit Card using 3D Secure 2 authentication, you need to include 3D Secure 2 fields in your initial request.
Most of these fields are optional but we recommend the implementation of optional fields, as this creates a smoother user experience and ensures a higher level of security.
Need more information on 3D Secure 2? Head to our general introduction to 3D Secure 2.

You must include "options": {"mode":"seamless"} in your request, otherwise Payment Page returns a regular payment URL that cannot be used in Seamless Mode.

Seamless Mode renders the payment form into an iframe. Therefore, you need to include "options": {`"frame-ancestor": "url"} in the request with your domain as the "url" value.
If you do not send "frame-ancestor" in the request, browsers will refuse to display the payment page in the iframe due to HTTP security policy.

2. Render the Seamless Payment Form

The response to the initial authorization request contains the payment-redirect-url.

Response to Authorization Request
{
    "payment-redirect-url": "https://paymentpage-test.getneteurope.com/seamless?wPaymentToken=XUcGTdnxwwCWPEP-YOeDmT05_hg1bKbaibLTpcdR8cU"
}

Use the WPP.seamlessRender function to render the payment form in a seamless iframe. Include the payment-redirect-url here:

WPP.seamlessRender({
    url: paymentredirecturl, // this is the payment link returned in response to your initial request
    wrappingDivId: "seamless-form-target",
    onSuccess: function (response) { // called when seamless form is successfully rendered
    },
    onError: function (errResp) { // called if seamless form failed to render
    }
});
This function renders only the payment form! The button with which consumers confirm their payment must be part of your checkout page. Bind the function to an interactive UI element, such as a button, in your HTML code.
Seamless Payment Form
Figure 2. Seamless payment form rendered into wrappingDivId
Render the Payment Form: Example from Getnet Demoshop
<html>
<head>
    <!-- ... -->
    <script src="https://paymentpage-test.getneteurope.com/loader/paymentPage.js" type="text/javascript"></script>
    <!-- ... -->
</head>
<body>
    <!-- ... -->
    <!-- the form will render in the following div -->
    <div id="seamless-form-target"></div>

    <!-- the following javascript will render the form; make sure to set paymentredirecturl -->
    <script type="text/javascript">
          // change the next line to include YOUR TOKEN
          var paymentredirecturl = "https://paymentpage-test.getneteurope.com/seamless?wPaymentToken=YOUR_TOKEN_HERE";

          // frame-ancestor in the initial request (Step 1) must match the domain you are using to test this
          WPP.seamlessRender({
               url: paymentredirecturl,
               wrappingDivId: "seamless-form-target",
               onSuccess: function (response) {
                 console.log(response);
               },
               onError: function (response) {
                 console.log(response);
               }
          });
    </script>
    <!-- ... -->
</body>
</html>
3. Submit the Payment

Now the payment form has been rendered and consumers can enter their payment information.

To submit that data, use the WPP.seamlessSubmit function:

WPP.seamlessSubmit({
    onSuccess: function (response) { // called when seamless form data is successfully submitted
    },
    onError: function (response) { //called when data submission fails
    }
});
Bind the function to an interactive UI element, such as a button, in your HTML code. The consumer can then click the button to submit the payment.
Submit the Payment: Example from Getnet Demoshop
<html>
<head>
    <!-- ... -->
    <script src="https://paymentpage-test.getneteurope.com/loader/paymentPage.js" type="text/javascript"></script>
    <!-- ... -->
</head>
<body>
    <!-- ... -->
    <!-- the form will render in the following div -->
    <div id="seamless-form-target"></div>

    <!-- the following javascript will render the form; make sure to set paymentredirecturl -->
    <script type="text/javascript">
          // change the next line to include YOUR TOKEN
          var paymentredirecturl = "https://paymentpage-test.getneteurope.com/seamless?wPaymentToken=YOUR_TOKEN_HERE";

          // frame-ancestor in the initial request must match the domain you are using to test this
          WPP.seamlessRender({
               url: paymentredirecturl,
               wrappingDivId: "seamless-form-target",
               onSuccess: function (response) {
                 console.log(response);
               },
               onError: function (response) {
                 console.log(response);
               }
          });
    </script>

    <!-- this code will generate the "Pay Now" button and enable the submission of the form -->
    <input id="getnet_pay_btn" type="button" onclick="pay()" value="Pay Now"/>
    <script type="text/javascript">
        function pay() {
            WPP.seamlessSubmit({
                onSuccess: function (response) {
                // called when seamless form data is successfully submitted with non-3D Secure credit card
                // see section 4 (Parse and Process the Payment Response) on how to deal with this data
                  console.log(response);
                },
                onError: function (response) {
                // called when seamless form data is successfully submitted with non-3D Secure credit card
                // see section 4 (Parse and Process the Payment Response) on how to deal with this data
                  console.log(response);
                }
             });
        }
    </script>
    <!-- ... -->
</body>
</html>
The function only submits the payment.

3D Secure Transaction Redirect

For 3D Secure transactions, Payment Page in Seamless Mode automatically redirects the consumer to the card provider 3D Secure authentication pages. There are no actions required from you for this process.

After 3D Secure authentication, the payment is further processed.

Depending on the outcome, the consumer is redirected to a success-/fail-/cancel-redirect-url. As the consumer leaves your page for 3D Secure authentication, these URLs need to be set up in the same way as those for HPP and EPP integrations.

This means that for 3D Secure Transactions, you need to include the success-/fail-/cancel-redirect-url in the initial request!

URLs for successful, failed, and canceled transactions can also be set during the initial merchant configuration and saved in the database. If you would like to change these default values, please contact Merchant Support.

More information on success-/fail-/cancel-redirect-url configuration can be found in Configuring Redirects and IPNs for Payment Page.

4. Parse and Process the Payment Response (Highly Recommended)

Once you have submitted the payment, and it has been processed, you receive a payment response. The payment response is sent in three parts: the response-signature-base64, the response-signature-algorithm, and the response-base64.

Object {
"response-signature-base64": "9JSIJ/G4Otz6KbAJTg20LSNOcvidhgGWAPR3BMXfbxQ=",
"response-signature-algorithm": "HmacSHA256",
"response-base64": "ewogICJwYXltZW50IiA6IHsKICAgICJmYWlsLXJlZGlyZWN0LXVybCIgOiAiaHR0cHM6Ly9kZW1vc2hvcC10ZXN0LndpcmVjYXJkLmNvbS9kZW1vc2hvcC8jIS9lcnJvciIsCiAgICAidHJhbnNhY3Rpb24tc3RhdGUiIDogInN1Y2Nlc3MiLAogICAgInN1Y2Nlc3MtcmVkaXJlY3QtdXJsIiA6ICJodHRwczovL2RlbW9zaG9wLXRlc3Qud2lyZWNhcmQuY29tL2RlbW9zaG9wLyMhL3N1Y2Nlc3MiLAogICAgInBheW1lbnQtbWV0aG9kcyIgOiB7CiAgICAgICJwYXltZW50LW1ldGhvZCIgOiBbIHsKICAgICAgICAibmFtZSIgOiAiY3JlZGl0Y2FyZCIKICAgICAgfSBdCiAgICB9LAogICAgInRocmVlLWQiIDogewogICAgICAiY2FyZGhvbGRlci1hdXRoZW50aWNhdGlvbi1zdGF0dXMiIDogIkEiLAogICAgICAiYXR0ZW1wdC10aHJlZS1kIiA6IGZhbHNlCiAgICB9LAogICAgImNhbmNlbC1yZWRpcmVjdC11cmwiIDogImh0dHBzOi8vZGVtb3Nob3AtdGVzdC53aXJlY2FyZC5jb20vZGVtb3Nob3AvIyEvY2FuY2VsIiwKICAgICJtZXJjaGFudC1hY2NvdW50LWlkIiA6IHsKICAgICAgInZhbHVlIiA6ICJjYWQxNmI0YS1hYmYyLTQ1MGQtYmNiOC0xNzI1YTRjZWY0NDMiCiAgICB9LAogICAgImN1c3RvbS1maWVsZHMiIDogewogICAgICAiY3VzdG9tLWZpZWxkIiA6IFsgewogICAgICAgICJmaWVsZC1uYW1lIiA6ICJlbGFzdGljLXBhZ2UtYXBpLjNkLm9yaWdpbmFsX3R4bl90eXBlIiwKICAgICAgICAiZmllbGQtdmFsdWUiIDogInB1cmNoYXNlIgogICAgICB9IF0KICAgIH0sCiAgICAidHJhbnNhY3Rpb24taWQiIDogImFkOWY5YjEyLTY4ODgtNDkxOC04N2NkLTZmYWRjNzRkYzRjOCIsCiAgICAiY29tcGxldGlvbi10aW1lLXN0YW1wIiA6ICIyMDE5LTAyLTExVDE1OjIzOjAwIiwKICAgICJyZXF1ZXN0ZWQtYW1vdW50IiA6IHsKICAgICAgImN1cnJlbmN5IiA6ICJFVVIiLAogICAgICAidmFsdWUiIDogMTAuMQogICAgfSwKICAgICJhdXRob3JpemF0aW9uLWNvZGUiIDogIjY4NzIwNiIsCiAgICAiY3NjLWNvZGUiIDogIk4iLAogICAgImFjY291bnQtaG9sZGVyIiA6IHsKICAgICAgImxhc3QtbmFtZSIgOiAibGFzdCIsCiAgICAgICJmaXJzdC1uYW1lIiA6ICJmaXJzdCIKICAgIH0sCiAgICAiY2FyZCIgOiB7CiAgICAgICJleHBpcmF0aW9uLW1vbnRoIiA6IDEsCiAgICAgICJleHBpcmF0aW9uLXllYXIiIDogMjAyMywKICAgICAgImNhcmQtdHlwZSIgOiAidmlzYSIsCiAgICAgICJtZXJjaGFudC10b2tlbml6YXRpb24tZmxhZyIgOiBmYWxzZQogICAgfSwKICAgICJzdGF0dXNlcyIgOiB7CiAgICAgICJzdGF0dXMiIDogWyB7CiAgICAgICAgImRlc2NyaXB0aW9uIiA6ICIzZC1hY3F1aXJlcjpUaGUgcmVzb3VyY2Ugd2FzIHN1Y2Nlc3NmdWxseSBjcmVhdGVkLiIsCiAgICAgICAgInNldmVyaXR5IiA6ICJpbmZvcm1hdGlvbiIsCiAgICAgICAgImNvZGUiIDogIjIwMS4wMDAwIgogICAgICB9LCB7CiAgICAgICAgImRlc2NyaXB0aW9uIiA6ICIzZC1hY3F1aXJlcjpQcm9vZiBvZiBhdXRoZW50aWNhdGlvbiBhdHRlbXB0IHdhcyBnZW5lcmF0ZWQuIiwKICAgICAgICAic2V2ZXJpdHkiIDogImluZm9ybWF0aW9uIiwKICAgICAgICAiY29kZSIgOiAiMjAwLjEwODQiCiAgICAgIH0gXQogICAgfSwKICAgICJwYXJlbnQtdHJhbnNhY3Rpb24taWQiIDogImFiMWI0MmI2LWIwYzktNGVmMC1iYjBjLTA1N2MzMjAzOTk1NyIsCiAgICAicGFyZW50LXRyYW5zYWN0aW9uLWFtb3VudCIgOiB7CiAgICAgICJjdXJyZW5jeSIgOiAiRVVSIiwKICAgICAgInZhbHVlIiA6IDEwLjEwMDAwMAogICAgfSwKICAgICJhcGktaWQiIDogIndwcCIsCiAgICAiZGV2aWNlIiA6IHsKICAgICAgImZpbmdlcnByaW50IiA6ICIzYmFiMTI2Zi05YjEzLWEzYmYtY2YwNS0yZTA5NjVmZGIwZGQiCiAgICB9LAogICAgImNhcmQtdG9rZW4iIDogewogICAgICAibWFza2VkLWFjY291bnQtbnVtYmVyIiA6ICI0MDEyMDAqKioqKio2MDAyIiwKICAgICAgInRva2VuLWlkIiA6ICI0ODE5MjUzODg4MDk2MDAyIgogICAgfSwKICAgICJ0cmFuc2FjdGlvbi10eXBlIiA6ICJwdXJjaGFzZSIsCiAgICAicmVxdWVzdC1pZCIgOiAiNGU4MTkyNDEtYTc1OS00NWYxLThmM2ItNWM3MTJlYjkyMzNmIgogIH0KfQ=="
}
  • response-base64 contains the payment data.

  • response-signature-base64 and the response-signature-algorithm, together with the Secret Key you receive upon signing a contract with Getnet, are required for calculating the security response signature. The security response signature is essential for verifying the payment status.
    Please consult Payment Page Security for details and examples of response signature verification.

In Seamless Mode, the Payment Page sends the final response containing the payment data to either of the following destinations, depending on the payment mode.

3D Secure Credit Card Payment

The Payment Page sends the final response containing the payment data to the success-redirect-url/fail-redirect-url specified in the initial request. This is the URL where the consumer is redirected to at the end of a payment session.

To parse and process the payment response of 3D Secure credit card payment, please consult Payment Page Security for details.

This is the decoded payment data contained in the example payment response provided above.

Decoded Payment Response
{
    "payment": {
        "transaction-state": "success",
        "payment-methods": {
            "payment-method": [
                {
                    "name": "creditcard"
                }
            ]
        },
        "three-d": {
            "cardholder-authentication-status": "A",
            "attempt-three-d": false
        },
        "merchant-account-id": {
            "value": "cad16b4a-abf2-450d-bcb8-1725a4cef443"
        },
        "custom-fields": {
            "custom-field": [
                {
                    "field-name": "elastic-page-api.3d.original_txn_type",
                    "field-value": "purchase"
                }
            ]
        },
        "transaction-id": "ad9f9b12-6888-4918-87cd-6fadc74dc4c8",
        "completion-time-stamp": "2019-02-11T15:23:00",
        "requested-amount": {
            "currency": "EUR",
            "value": 10.1
        },
        "authorization-code": "687206",
        "csc-code": "N",
        "account-holder": {
            "last-name": "last",
            "first-name": "first"
        },
        "card": {
            "expiration-month": 1,
            "expiration-year": 2023,
            "card-type": "visa",
            "merchant-tokenization-flag": false
        },
        "statuses": {
            "status": [
                {
                    "description": "3d-acquirer:The resource was successfully created.",
                    "severity": "information",
                    "code": "201.0000"
                },
                {
                    "description": "3d-acquirer:Proof of authentication attempt was generated.",
                    "severity": "information",
                    "code": "200.1084"
                }
            ]
        },
        "parent-transaction-id": "ab1b42b6-b0c9-4ef0-bb0c-057c32039957",
        "parent-transaction-amount": {
            "currency": "EUR",
            "value": 10.1
        },
        "api-id": "up3-wpp"
        },
        "card-token": {
            "masked-account-number": "401200******6002",
            "token-id": "4819253888096002"
        },
        "transaction-type": "purchase",
        "request-id": "4e819241-a759-45f1-8f3b-5c712eb9233f"
    }
}
Field Table
Field (JSON) Data Type Description

transaction-state

String

The current transaction state. Possible values: - in-progress - success - failed

Typically, a transaction starts with state in-progress and finishes with state either success or failed. This information is returned in the response only.

payment-method

name

String

The name of the payment method used for the transaction.

three-d

cardholder-authentication-status

String

Result of the 3D Secure check.

attempt-three-d

Boolean

Indicates whether the transaction should use the 3-D Secure workflow.

merchant-account-id

value

String

A unique identifier by us to every merchant account.

custom-field

field-name

String

Custom field.

field-value

String

Custom field.

transaction-id

String

A unique identifier assigned by us to every transaction. Used when searching for or referencing to it later.

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time & date when the transaction was executed.
Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount.
Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction.

authorization-code

String

Provider authorization code.

csc-code

String

Code indicating Card Verification Value (CVV/CVC) verification results.

account-holder

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

card

expiration-month

Numeric

The expiration month of the card used in the transaction.

expiration-year

Numeric

The expiration year of the card used in the transaction.

card-type

String

The type/provider of the card used in the transaction.

merchant-tokenization-flag

Boolean

Indicates whether Cardholder card data was stored by the Merchant for future transactions. Maps to the Visa field Stored Credential.

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message. Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

parent-transaction-id

String

The unique identifier of a transaction that is being referenced (sometimes referred to as the "original transaction").

parent-transaction-amount

currency

String

The currency of the requested/contested transaction amount.
Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction.

api-id

String

Description of the transaction for account holder’s bank statement purposes.

card-token

token-id

String

A unique identifier assigned to every card token.

masked-account-number

String

The masked code that represents the account (card) number used in the transaction.

transaction-type

String

The requested transaction type.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing to it later.