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