EPS

Electronic Payment Standard (EPS) is an online payment system used in Austria.

About EPS

EPS is the official online payment system of the Austrian banks.

To authorize a payment, the customer either provides a BIC code, or accesses the online banking interface of their bank.

Once the credentials are entered, the payment is considered as a secure direct bank transfer. It ensures important data is not exchanged between you and the customer.

Accept an EPS payment

To accept an EPS payment, follow the steps below.

When testing, do not use real customer data. Use the test data prepared by Unzer.

Step 1: Create a payment resource

Make a POST call to /types/eps, with the following parameters in the request body:

Parameter	Required	Type	Default	Description
`bic`	Yes	String	`/`	The customer’s BIC.

POST https://api.unzer.com/v1/types/eps/

Body: 
{
    "bic": "STZZATWWXXX"
}

{
  "id": "s-eps-9rxdhskuhnea",
  "method": "EPS",
  "recurring": false,
  "geoLocation": {
    "clientIp": "115.77.189.143",
    "countryCode": "DE"
  },
  "bic": "STZZATWWXXX"
}

Property	Type	Description
`id`	String	The ID of the resource that you created.
`method`	String	The payment method.
`recurring`	Boolean	Indicates if this is a recurring payment.
`clientIp`	String	The IP address of the device used for the payment.
`countryCode`	String	The country associated with `clientIp`, displayed in the ISO 3166-1 alpha-2 format.
`bic`	String	The customer BIC.

Step 2: Make a `charges` call

Make a POST call to payments/charges with the following parameters in the request body:

Parameter	Required	Type	Default	Description
`amount`	Yes	Number	`/`	The transaction amount
`currency`	Yes	String	`/`	The transaction currency, in the ISO 4217 alpha-3 format.
`returnUrl`	No	String	`/`	After the customer confirms the payment on the EPS payment page, `returnUrl` is called to redirect customer to the shop’s website.
`typeId`	Yes	String	`/`	The newly-created payment type ID that you received in response to creating an `eps` resource (Step 1).

POST https://api.unzer.com/v1/payments/charges
   
Body:
{
  "amount":       "12.4500",
  "currency":     "EUR",
  "returnUrl":    "https://www.unzer.com",
  "resources": {
    "typeId":        "s-eps-9ta3utzr8a98",
  }
}

{
  "id" : "s-chg-1",
  "isSuccess" : false,
  "isPending" : true,
  "isError" : false,
  "redirectUrl" : "https://dev-payment.unzer.com/v1/redirect/eps/s-3DCCtPb5nZkS",
  "message" : {
    "code" : "COR.000.200.000",
    "customer" : "Transaction Pending"
  },
  "amount" : "50.0000",
  "currency" : "EUR",
  "returnUrl" : "https://www.unzer.com",
  "date" : "2019-01-09 16:33:44",
  "resources" : {
    "customerId" : "s-cst-ed5801724a21",
    "paymentId" : "s-pay-15713",
    "basketId" : "",
    "metadataId" : "",
    "typeId" : "s-eps-9ta3utzr8a98"
  },
  "orderId" : "",
  "processing" : {
    "uniqueId" : "31HA07BC811CBAA376AE2797749D29DE",
    "shortId" : "4109.7802.3776"
  }
}

Property	Type	Description
`id`	String	The transaction’s unique ID.
`isSuccess`	Boolean	Set to `true` if the transaction was successful.
`isPending`	Boolean	Set to `true` if the transaction is pending (e.g. if a redirect to an external system is required).
`isError`	Boolean	Set to `true` if an error occurs.
`redirectUrl`	String	The URL to which the customer gets redirected after the payment.
`code`	String	A unique ID of the message. For details, go to Error `code` structure.
`customer`	String	Message displayed to the customer.
`amount`	Number	The transaction amount.
`currency`	String	The transaction currency, in the ISO 4217 alpha-3 format.
`returnUrl`	String	The URL to redirect the customer to after the payment is completed.
`date`	String	Date and time of the transaction.
`customerId`	String	The ID of the `customers` resource.
`paymentId`	String	The ID of the related payment resource.
`basketID`	String	The ID of the related basket resource.
`metadataId`	String	The ID of the related `metadata` resource.
`typeId`	String	The newly-created payment type ID that you received in response to creating an `eps` resource (Step 1).
`orderId`	String	The ID of the related order resource.
`uniqueId`	String	The ID of the transaction process.
`shortId`	String	The short ID of the transaction process.

Step 3: Forward the customer to the redirect URL

After you charge the eps resource, implement the following flow:

Redirect the customer to the redirectURL.
The customer is forwarded to the EPS payment page.
After a successful payment or cancellation, the customer is redirected to the returnURL that you specified in the charges call (Step 2).

Step 4: Check the payment status

After the customer is redirected to the returnUrl, check the status of the payment.

Make a GET call with the following parameters in the request path:

Parameter	Required	Type	Description	Example
`resource_ID`	Yes	String	The returned ID of the `eps` resource that you created in Step 1.	`s-eps-9rxdhskuhnea`
`transaction_ID`	Yes	String	The transaction’s unique ID that you received in Step 2.	`s-chg-1`

GET https://api.unzer.com/v1/payments/{resource_ID}>/charges/{transaction_ID}

{
  "id" : "s-chg-1",
  "isSuccess" : true,
  "isPending" : false,
  "isError" : false,
  "redirectUrl" : "",
  "message" : {
    "code" : "COR.000.100.112",
    "customer" : "Request successfully processed in 'Merchant in Connector Test Mode'"
  },
  "amount" : "50.0000",
  "currency" : "EUR",
  "returnUrl" : "http://www.unzer.com",
  "date" : "2019-01-10 13:10:57",
  "resources" : {
    "customerId" : "s-cst-99d06a558093",
    "paymentId" : "s-pay-71655",
    "basketId" : "",
    "metadataId" : "",
    "typeId" : "s-eps-nxutppqdwlvw"
  },
  "processing" : {
    "uniqueId" : "31HA07BC812983BC3E54797D57731593",
    "shortId" : "4110.5203.7034"
  }

Implement the EPS UI on your website

Web integration
Before implementing the EPS UI on your website, read the web integration topic.

Step 1: Load our JS script and CSS stylesheet

Include Unzer’s script and stylesheet on your website.

Always load the script and stylesheet directly from https://static.unzer.com:

<link rel="stylesheet" href="https://static.unzer.com/v1/heidelpay.css" />
<script type="text/javascript" src="https://static.unzer.com/v1/heidelpay.js"></script>

Faster load time
To make your website load faster, insert the script at the bottom of your HTML document.

Step 2: Create a `heidelpayInstance`

Create a heidelpayInstance with your public key:

var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');

Step 3: Create your HTML form

Create an HTML form, into which the EPS UI will be inserted:

<form id="payment-form" class="heidelpayUI form" novalidate>
  <div id="example-eps" class="field"></div>
  <button class="heidelpayUI primary button fluid" type="submit">Pay</button>
</form>

Localization
We support localization. You can create your HTML form in different languages.

Step 4: Create an EPS resource

To create a new EPS resource, call the heidelpayInstance.EPS method:

// Creating an EPS instance
var EPS = heidelpayInstance.EPS()
// Rendering input field
EPS.create('eps', {
  containerId: 'example-eps'
});

The IDs must match
Make sure that the IDs in your HTML and JavaScript files match. For more information on how to create your HTML form correctly, go to web integration.

Step 5: Create your resource ID and submit the form

Add the code that handles the form submission. These are the actions the code sample below performs:

Gets the form element by its ID.
Adds an event listener to the submit button.
Creates a Promise with .createResource and submits the form.

// Handling payment form's submission
var form = document.getElementById('payment-form');
// Handle EPS form submission.
form.addEventListener('submit', function (event) {
  event.preventDefault();
  EPS.createResource()
    .then(function (data) {
    // Success
  })
    .catch(function (error) {
    // Error
  })
});

Step 6: Review the code

View the complete code samples that you can use to implement the EPS UI on your website:

<form id="payment-form" class="heidelpayUI form" novalidate>
  <div id="example-eps" class="field"></div>
  <button class="heidelpayUI primary button fluid" type="submit">Pay</button>
</form>

// Creating an Unzer instance with your public key
var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');

// Creating an EPS instance
var EPS = heidelpayInstance.EPS()
// Rendering input field
EPS.create('eps', {
  containerId: 'example-eps'
});

// Handling payment form's submission
var form = document.getElementById('payment-form');
form.addEventListener('submit', function (event) {
  event.preventDefault();
  EPS.createResource()
    .then(function (data) {
    // Success
    })
    .catch(function (error) {
    // Error
    })
});

Optional: Update an EPS resource

You can update the value of an existing EPS resource. The update process is very similar to creating a new EPS resource, with the following differences:

You need to pass the resourceId when calling create().
At the end, you need to run updateResource() instead of createResource().

The HTML is the same as during the create resource process.

// EPS JavaScript (updateResource)
// Creating an Unzer instance with your public key
var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');

// Creating an EPS instance
var EPS = heidelpayInstance.EPS()
// Rendering input field
EPS.create('eps', {
  containerId: 'example-eps',
  resourceId: 's-eps-resourceid', // ID of the resource you want to update
});

// Handling payment form's submission
var form = document.getElementById('payment-form');
form.addEventListener('submit', function (event) {
  event.preventDefault();
  EPS.updateResource()
    .then(function (data) {
    // Success
    })
    .catch(function (error) {
    // Error
    })
});

UI reference

Constructors

Constructor	Description
`heidelpay.EPS()`	Initializes an `EPS` object.

Methods

Method	Type	Description	Returns
`create(type, options)`	Promise	Creates an input field for the EPS payment method specified by the `type` parameter.	An object containing success or error details.
`createResource()`	Promise	Creates a Promise object for input validation. Either gets resolved (validation passed) or rejected (validation didn’t pass).	An object containing success or error details. Success: `{id: String,` `method: String,` `bic: String,` `recurring: Boolean}` Error: `{}`
`updateResource()`	Promise	Creates a Promise and submits the new data from the form. If resolved, the old `BIC` data is updated.	An object containing success or error details. Success: `{id: String,` `method: String,` `bic: String,` `recurring: Boolean}` Error: `{}`

`create` properties

Property	Type	Description
`type`	String	Specifies the type of input field to be created. Valid value: `eps`
`options`	Object	A JSON with various options for the created input field.
`containerId`	String	The HTML `id` of the DOM element, where the UI component will be inserted. Example: `containerId: 'eps-element-id-number'`
`resourceId`	String	The `id` of the created resource you wish to update. You need to pass the `resourceId` before before using the `updateResource` method.

`createResource` response properties

Property	Type	Description
`id`	String	The ID of the returned `/types/eps` resource.
`method`	String	The chosen payment method.
`bic`	String	The customer BIC.
`recurring`	Boolean	Indicates if this is a recurring payment.

`updateResource` response properties

Property	Type	Description
`id`	String	The ID of the returned `/types/eps` resource.
`method`	String	The chosen payment method.
`bic`	String	The customer BIC.
`recurring`	Boolean	Indicates if this is a recurring payment.