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.
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>
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');
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.
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 | 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 | Masked value for the inputted email value. It will only be returned if valid email address has been passed. |