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>

Faster load time
To make your website load faster, insert scripts 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

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.