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 an eps 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": "VN"
  },
  "bic": "STZZATWWXXX"
}
Property Type Description
id String The ID of the resource that you just 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:

  1. Redirect the customer to the redirectURL.
  2. The customer is forwarded to the EPS payment page.
  3. 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:

  1. Gets the form element by its ID.
  2. Adds an event listener to the submit button.
  3. 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.