PayPal UI

Implement the PayPal UI on your website.

Introduction

In this guide you will learn how to integrate PayPal on your website. If you haven’t read the web integration walkthrough yet, we recommend you do that first.

Also, we suggest you you should read our detailed explanation of PayPal.

There are 2 different ways to Web implementation of PayPal payments:

  • PayPal redirect payment without email input field
  • PayPal redirect payment with email input, which we’ll explain in more detail below

The two options are part of redirect payment types which will forward the user to a dedicated payment site.

Key difference between PayPal with and PayPal without email input field
Once redirected, if the user provides her/his email address, it will automatically update the email field on the PayPal page. In other case, the user will land on a blank new PayPal page.

https://heidelpay.github.io/heidelpayUIExamples/iframes/others.html

Step 1: Setup

First, you need to include Unzer’s script and stylesheet on your website. They must always be loaded 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>
Good practice
Even though it’s not mandatory in html, it’s considered good practice to place scripts at the bottom of your HTML document. This way your website will display and load faster.

Next, create a Unzer instance with your public key:

// Creating an Unzer instance with your public key
var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');
Showcase keys
In the example above, we’ve used a random API key for showcase purposes. For production usage you should replace it with your personal public key.

If you don’t have a public and private key yet, you can get them by sending an e-mail to our support.

Additionally we support localization, in case you want your form to be be in a specific language.

Step 2: Create your form

If you decided you want to create an instance of PayPal with an email field, you will have to create a form (in case you want a simpler PayPal implementation, check our redirect payments page.

Email input field
Even though you will provide a PayPal instance with the email, the input field that we provide is optional for the end-user (i.e. the user should still be able to press the checkout button without adding any information to the email input field)

Inside the form, you will have to create two elements: a button and a container (a simple div) for the email input field. Make sure you provide unique IDs for the elements.

<form id="payment-form-paypal">
  <div id="container-example-paypal"></div>

  <button type="submit">Pay</button>
</form>

Step 3: Create a PayPal instance and add an event listener

Finally, you will have to create a PayPal instance, add an event listener to the form and handle the form’s submission.

The PayPal create method will ask for two arguments, the first one which will enable you to add the email input field, and the second one which will provide the ID of the container you wish to hold the input field.

// Creating a PayPal instance
var Paypal = heidelpayInstance.Paypal()
Paypal.create('email', {
  containerId: 'container-example-paypal'
})

var form = document.getElementById('payment-form-paypal')
form.addEventListener('submit', function(event) {
  event.preventDefault()
  
  Paypal.createResource()
    .then(function(data) {
    // Handle success
    })
    .catch(function(error) {
    // Handle error
    })
});

After creating a PayPal instance by calling the .Paypal() constructor on the previously created heidelpayInstance object, we will render the PayPal HTML by calling the create() method.

We also add a simple submit event listener to the form. After the form is submitted, a promise is created, which either gets resolved or rejected.

In case it gets resolved, you will receive a resourceId and method that points to PayPal back. All that’s left to do now is to pass those variables to your back-end.


Congratulations! You’ve successfully integrated PayPal as a payment method on your website!


Updating PayPal

You can also choose to update the value of already created PayPal resource. The updating process is almost identical to creating a new PayPal resource. The main difference is that you will need to pass the resourceId inside the second argument when calling the create() method, and finally running the updateResource() instead of the createResource() method. The complete process is explained in the code box below (note that HTML will be the same as when following the createResouce() process).

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

// Creating a PayPal instance
var Paypal = heidelpayInstance.Paypal()
// Rendering input field
Paypal.create('email', {
  containerId: 'container-example-paypal',
  resourceId: 's-ppl-resourceid', // ID of the resource you want to update
})

// Handling payment form's submission
var form = document.getElementById('payment-form-paypal')
form.addEventListener('submit', function(event) {
  event.preventDefault()

  Paypal.updateResource()
    .then(function(data) {
    // Handle success
    })
    .catch(function(error) {
    // Handle error
    })
});

Constructors

Constructor Description
heidelpay.Paypal() Initializes the PayPal object.

Method summary

Type Method Description
void create(String type, Object options) Creates the specified input fields and mounts them onto the declared DOM element.
void addEventListener(String name, Function paypalEventHandler) Provides an option to add a custom eventHandler, which informs if inputed email value is valid.
Promise createResource() Creates a promise object for input validation. Either gets resolved (validation passed) or rejected (validation didn’t pass).
Promise updateResource() Creates a promise object for input validation. Either gets resolved (validation passed) or rejected (validation didn’t pass).

create

Method

void create(String type, Object options)

Description

Creates an email input field for PayPal payment method specified by the type parameter. Additionally, you can pass different options as key value pairs inside the options parameter.

Properties

Type Property Description
String type Specifies the type of input field to be created.
Valid values: email
Object options A JSON with various options for the created input field.

options

Type Property Description
String containerId The HTML id of the DOM element, where the UI component will be inserted.
Example:
containerId: 'container-example-paypal'
String resourceId The id of the created resource you wish to update. It is required to be passed before using updateResource method.

addEventListener

Method

void addEventListener(String name, Function paypalEventHandler)

Description

Enables you to add a customer eventHandler function that will receive an object which will inform whether the data added to the email input field was validated.

Properties

Type Property Description
String name Specifies the type of the event listener.

Valid values: ‘change’
Function paypalEventHandler Place for a custom function. It receives an object with the success key, which can be true or false.

createResource

Method

Object createResource()

Description

Creates a promise and submits the form’s data. The payment type /types/paypal is created and either resolved or rejected. In both cases an object is returned.

Returns

An object with the following structure:

  • Success: {id: String, method: String, email: String}
  • Error: {}
Type Property Description
String id The returned resource ID.
String method The payment method.
String email Masked value for the inputted email value. It will only be returned if valid email address has been passed.

updateResource

Method

Object updateResource()

Description

Creates a promise and submits the form’s new data. If resolved, the old email data will be updated.

Returns

An object with the following structure:

  • Success: {id: String, method: String, email: String}
  • Error: {}
Type Property Description
String id The returned resource ID. This value will not change after updating the resource.
String method The payment method. This value will not change after updating the resource.
String email Masked value for the inputted email value. It will only be returned if valid email address has been passed.