EPP Integration Guide

Overview

To integrate the Embedded Payment Page (EPP) in your shop, use a simple 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 Payment Page. This POST request is secured by basic access authentication.

  2. Render/create the payment page: Payment Page returns an initial response URL.

    • If the initial POST request is correct, use the response URL to render the embedded payment page as an overlay to the checkout page. The consumer fills out the required fields on the payment page and submits the payment. 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. Parse and process the payment response: The payment is processed. Depending on the result (successful, pending, failed or canceled), the consumer is redirected to the respective page. The Payment Page sends a POST request containing base64 encoded payment data to the same URL. It is highly recommended that you parse and process this base64 encoded response to verify the payment.

    The payment process is complete.

Payment-Processing Example

This is an example of a credit card transaction to show how to process a payment with the Embedded Payment Page.
For more supported payment methods and payment-method-specific integration guides, go to Payment Methods with Payment Page.

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

Payment processing with the Payment Page generally follows the same steps:

  1. Create a payment session (initial request).

  2. Render the embedded payment page.

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

We provide ready-made JSON samples for each step of this process. Use a tool such as Postman to test them.

Setup and Test Credentials

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

Test Credentials

URI (API Endpoint)

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

Merchant Account ID (MAID)

To be determined

Username

To be determined

Password

To be determined

Secret Key (used for response verification)

To be determined

Test Card

Card number

4012000300201199

Expiration date

01/23

CVV

199

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 NzAwMDAtQVBJREVNTy1DQVJEOm9oeXNTMC1kdmZNeA==

The Authorization header must be formatted as: Authorization=Basic + base64 (username:password)

You can try it using the authorization headers above.

Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "7a6dd74f-06ab-4f3f-a864-adc52687270a"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "authorization",
    "requested-amount": {
      "value": 10,
      "currency": "EUR"
    },
    "account-holder": {
      "first-name": "John",
      "last-name": "Doe"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "creditcard"
        }
      ]
    },
    "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": "embedded",
    "frame-ancestor": "https://example.com"
  }
}
Field Table
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.

account holder

first-name

String

Required

32

The first name of the account holder.

last-name

String

Required

32

The last name of the account holder.

payment-method

name

String

Optional

15

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

success-redirect-url

String

Optional

256

The URL to which the consumer is redirected after a 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 an unsuccessful 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 having canceled a 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 seamless and embedded.

frame-ancestor

String

Required

256

The URL of the checkout page where the iframe is rendered.

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.

Which Payment Methods Can I Choose?

Leave out the payment-methods object from the request. Payment Page will show a grid of all available payment methods (based on your merchant configuration).

Alternatively, check out Payment Methods with Payment Page for an overview of all supported payment methods.

2. Embed the Payment Page

The payment page is in this case an overlay window. It is created using the payment-redirect-url, contained in the response to the initial authorization request.

Response to Authorization Request
{
  "payment-redirect-url": "https://paymentpage-test.getneteurope.com/?wPaymentToken=f0c0e5b3-23ad-4cb4-abca-ed80a0e770e7"
}

Embedding the Payment Page in your Checkout Page Using WPP.embeddedPayUrl

You can use our predefined function to embed the payment page:

  1. 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>

    Make sure to pass the payment-redirect-url value from the initial response to the WPP.embeddedPayUrl function and call it to render the payment page.

  2. Submit the initial payment request on the backend.

  3. Call the WPP.embeddedPayUrl(payment-redirect-url) function in your HTML code to render the new pop-up window.

    <script type="text/javascript">WPP.embeddedPayUrl("https://paymentpage-test.getneteurope.com/?wPaymentToken=f0c0e5b3-23ad-4cb4-abca-ed80a0e770e7")</script>

The consumer is redirected to the payment form. There they enter their data and submit the form to confirm the payment. The response can either:

  • be successful (transaction-state: success)

  • fail (transaction-state: failed)

  • or the consumer canceled the payment before/after submission (transaction-state: failed).

The transaction result is displayed as the value of transaction-state in the payment response. Canceled payments are returned as "transaction-state" : "failed", but the status description indicates it was canceled. More information (including the status code) can also be found in the payment response in the statuses object.

In any case, a base64 encoded response containing payment information is sent to the corresponding redirection URL (success-redirect-url, cancel-redirect-url, or fail-redirect-url).

See Configuring Redirects and IPNs for Payment Page for more information on redirection targets after payment.

Parse and Process the Payment Response (Highly Recommended)

Where Can I Find the Payment Response?

Payment Page sends the final response to the success/fail page where the consumer is redirected to at the end of the payment session. This final response contains the payment data in a base64 encoded JSON format. It is sent with a POST request as form data response-base64.

Base64

Before you are able to parse and process the payment response, you need to decode it.

To test this:

  • Copy and paste the payment-redirect-url into your browser.

  • Open your browser’s console and complete the payment with the credit card information provided above.

  • In your browser’s console, find the form data response-base64 (see screenshot).

  • Copy and paste the response into a base64 decoder of your choice, e.g. Base64 Decode.

  • Decode the response to view the payment response details.

You can find a decoded payment response example below.

Parse and Process the Payment Response (Decoded Payment Response)
{
  "payment": {
    "transaction-type": "authorization",
    "transaction-id": "08649015-eb17-4c67-ab5f-d132af616e02",
    "completion-time-stamp": "2018-12-19T12:02:26",
    "card-token": {
      "token-id": "4242796444090018",
      "masked-account-number": "420000******0018"
    },
    "merchant-account-id": {
      "value": "7a6dd74f-06ab-4f3f-a864-adc52687270a"
    },
    "transaction-state": "success",
    "payment-methods": {
      "payment-method": [
        {
          "name": "creditcard"
        }
      ]
    },
    "cancel-redirect-url": "https://demoshop-test.getneteurope.com/demoshop/#/cancel",
    "success-redirect-url": "https://demoshop-test.getneteurope.com/demoshop/#/success",
    "fail-redirect-url": "https://demoshop-test.getneteurope.com/demoshop/#/error",
    "api-id": "{api-id]"
  },
  "request-id": "28285dbd-ecd3-49bd-a7e5-0239affa2448",
  "requested-amount": {
    "currency": "EUR",
    "value": 10
  },
  "statuses": {
    "status": [
      {
        "description": "3d-acquirer:The resource was successfully created.",
        "severity": "information",
        "code": "201.0000"
      }
    ]
  },
  "authorization-code": "801433",
  "account-holder": {
    "first-name": "John",
    "last-name": "Doe"
  },
  "descriptor": "demo descriptor"
}
Field Table
Field (JSON) Data Type Description

transaction-type

String

The requested transaction type.

transaction-id

String

A unique identifier to every transaction (by ). 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).

card token

token-id

String

A unique identifier assigned to every card token.

masked-account-number

String

This is the masked card account number of the consumer.

merchant-account-id

value

String

A unique identifier assigned by us to every merchant account.

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-mode

name

String

The name of the payment method used for the transaction.

cancel-redirect-url

String

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

success-redirect-url

String

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

fail-redirect-url

String

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

api-id

String

Identifier of the currently used API.

request-id

String

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

requested-amount

currency

String

The currency of the requested/contested transaction amount.

value

Numeric

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

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

authorization-code

String

Output code for transaction type authorization.

account-holder

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

descriptor

String

Describes the transaction.

For more information on redirect URLs, see Configuring Redirects and IPNs for Payment Page.
For response verification examples, see Payment Page Security.
For payment-method-specific requests, head over to the Payment Methods with Payment Page.