GetNet Documentation

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.

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

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:

Create a payment session (initial request).
Render the embedded payment page.
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)	5c4a8a42-04a8-4970-a595-262f0ba0a108
Resolver Category	GetnetEuropeTest
Username	515225-GetnetEuropeTEST
Password	4cHLRE-Q7YcAP
Secret Key (used for response verification)	5ac555d4-e7f7-409f-8147-d82c8c10ed53

Test Card
Card number	4012000300201199
Expiration date	01/25
CVV	199

Test Card

Card number

4012000300201199

Expiration date

01/25

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": "5c4a8a42-04a8-4970-a595-262f0ba0a108"
    },
    "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"
  }
}

Create a Payment Session (Initial Request with resolver category)

The request below generates a payment page that includes all payment methods assigned to the specified resolver category.

{
  "payment": {
    "merchant-account-resolver-category": "GetnetEuropeTest",
    "request-id": "{{$guid}}",
    "transaction-type": "auto-sale",
    "requested-amount": {
      "value": 10,
      "currency": "EUR"
    },
    "account-holder": {
      "first-name": "John",
      "last-name": "Doe"
    },
    "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"
  }
}

Create a Payment Session (Initial Request with resolver category and allowed payment methods)

It is also possible to generate a payment page with a subset of the payment methods assigned to one resolver category. You just need to list the payment methods as in the sample below.

{
  "payment": {
    "merchant-account-resolver-category": "GetnetEuropeTest",
    "request-id": "{{$guid}}",
    "transaction-type": "auto-sale",
    "requested-amount": {
      "value": 10,
      "currency": "EUR"
    },
    "account-holder": {
      "first-name": "John",
      "last-name": "Doe"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "creditcard"
        },
        {
          "name": "paypal"
        },
        {
          "name": "ideal"
        }
      ]
    },
    "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.
`requested-amount`	`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.
`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`.
`options`	`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=<DYNAMIC_TOKEN>"
}

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

You can use our predefined function to embed the payment 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>
```
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.
Submit the initial payment request on the backend.

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=<DYNAMIC_TOKEN>")</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.

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.
`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.
`requested-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.
`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.

GetNet Documentation

EPP Integration Guide

Overview

Payment-Processing Example