Unzer Bank Transfer

Unzer Bank Transfer lets your customers pay directly from their bank account.

About Unzer Bank Transfer

Unzer Bank Transfer lets you accept a direct transfer from the customer’s bank account.

The service grants you access to the payer’s online bank account and performs any tasks necessary to make the transfer.

The customer needs to provide their bank account login credentials and authorize the transfer through their one-time password (OTP) device, usually via a transaction authentication number (TAN) received in a text message.

Accept an Unzer Bank Transfer payment

To accept an Unzer Bank Transfer payment, follow the steps below.

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

Step 1: Create a pis resource

To start an Unzer Bank Transfer, create a pis resource first.

Make an empty-body POST call to types/pis:

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

Body: {}
{
    "id": "s-pis-ynkylhm788ro",
    "method": "PIS",
    "recurring": false,
    "geoLocation": {
        "clientIp": "115.77.189.143",
        "countryCode": "VN"
    }
}
Property Type Description
id String The ID of the pis 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.

Step 2: Make a charges call

To charge the Unzer Bank Transfer resource, make a payments/charges call with the following parameters in the request body:

Parameter Required Type Default Description Example
amount Yes Number / The amount to be charged. 50
currency Yes String / The transaction currency, in the ISO 4217 alpha-3 format. EUR
returnUrl No String / After the customer confirms the payment on the Unzer Bank Transfer payment page, returnUrl is called to redirect customer to the shop’s website. https://www.unzer.com
typeId Yes String / The newly-created payment type ID that you received in response to creating an Unzer Bank Transfer resource (Step 1). s-pis-ynkylhm788ro
POST https://api.unzer.com/v1/payments/charges

Body:
{
  "amount" : "50",
  "currency" : "EUR",
  "returnUrl" : "https://www.unzer.com",
  "resources" : {
    "typeId" : "s-pis-ynkylhm788ro"
  }
}
{
  "id" : "s-chg-1",
  "isSuccess" : false,
  "isPending" : true,
  "isError" : false,
  "redirectUrl" : "https://payment.unzer.com/v1/redirect/pis/s-9rsh7LSsD0pK",
  "message" : {
    "code" : "COR.000.200.000",
    "customer" : "Transaction Pending"
  },
  "amount" : "50.0000",
  "currency" : "EUR",
  "returnUrl" : "http://www.unzer.com",
  "date" : "2018-11-23 14:01:38",
  "resources" : {
    "customerId" : "",
    "paymentId" : "s-pay-32290",
    "metadataId" : "",
    "typeId" : "s-pis-ynkylhm788ro"
  },
  "processing" : {
    "uniqueId" : "31HA07BC812B2DBB52602C09F2675A2D",
    "shortId" : "4069.0809.8626"
  }
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.
metadataId String The ID of the related metadata resource.
typeId String The newly-created payment type ID that you received in response to creating a pis resource (Step 1).
uniqueId String The ID of the transaction process.
shortId String The short ID of the transaction process.

Implement the Unzer Bank Transfer UI

To quickly integrate Unzer Bank Transfer into your website, implement our ready-made UI components.

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>

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

Because your customer doesn’t need to enter any information, you just need to create a simple HTML button::

<form id="payment-form">
  <button type="submit">Pay</button>
</form>
Localization
We support localization. You can create your HTML form in different languages.

Step 4: Create a new Unzer Bank Transfer resource

To create a new Unzer Bank Transfer instance, call the heidelpayInstance.UnzerBankTransfer() method:

var UnzerBankTransfer = heidelpayInstance.UnzerBankTransfer()

Step 5: Add an event listener and submit the form

Now get the HTML form by its unique ID and add an event listener.

Inside, create a Promise on the unzerBankTransfer object. The Promise gets either resolved or rejected:

var form = document.getElementById('payment-form');
form.addEventListener('submit', function(event) {
  event.preventDefault();
  UnzerBankTransfer.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 Unzer Bank Transfer UI on your website.

Make sure to import your own JavaScript and CSS files, as well as unzer.js and unzer.css.

<form id="payment-form">
  <button type="submit">Pay</button>
</form>
// Creating an Unzer instance with your public key
var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');
// Creating an UnzerBankTransfer instance
var UnzerBankTransfer = heidelpayInstance.UnzerBankTransfer()

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

UI reference

Constructors

Constructor Description
heidelpay.UnzerBankTransfer() Initializes the Unzer Bank Transfer object.

Methods

Method Type Description Returns
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}

Error:
{}
Property Type Description
id String The returned /types/pis resource ID.
method String The payment method.