PayPal

PayPal is one of the world’s most popular online payment systems.

About PayPal

PayPal supports online money transfers and serves as an electronic alternative to cheques and money orders.

The customer signs up for a PayPal account and provides their payment details, which are then used during the payment process.

PayPal has also introduced PayPal Express Checkout for a faster checkout experience. The customer does not need to enter their address details when they are paying on your website. For more details, see PayPal Express.

Accept a PayPal payment

To accept a PayPal payment, follow the steps below.

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

Step 1: Create a `paypal` resource

Make a POST call to /types/paypal, with the following parameters in the request body:

Parameter	Required	Type	Default	Description
`amount`	Yes	Number	`/`	The amount to be charged.
`currency`	Yes	String	`/`	The transaction currency, in the ISO 4217 alpha-3 format.
`basketId`	Optional	String	`/`	The ID of the related basket resource.
`customerId`	Optional	String	`/`	The ID of the `customers` resource.
`email`	Optional	String	`/`	The customer’s email address.

PayPal Express
For PayPal Express, the Content-Type is application/com.unzer.api.types.paypal.v2+json in the Headers parameter.

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

Body:
{
  "amount": "100",
  "currency": "EUR",
  "basketId":"s-bsk-123",
  "customerId":"s-cst-123",
  "email": "tester1@gmail.com"
}

{
  "id": "s-ppl-skki29gw2fue",
  "method": "paypal",
  "recurring": false,
  "geoLocation": {
    "clientIp": "127.0.0.1",
    "countryCode": "DE"
  },
  "email": "t*****1@n******a"
}

Property	Type	Description
`id`	String	The ID of the `paypal` resource that you just created.
`method`	String	The payment method.
`recurring`	Boolean	Indicates if this is a recurring payment.
`clientIp`	String	The current IP address of the device that the customer used for the payment.
`countryCode`	String	The country associated with the `clientIp`, displayed in the ISO 3166-1 alpha-2 format.
`email`	String	The customer’s email address.

PayPal Express
For PayPal Express, you will get the customer details when the PayPal flow is completed successfully. You must create Paypal Express button callbacks or webhook notifications to get the customer details.

Step 2: Charge or authorize

After you create a paypal resource, you have two options:

Option 1: Charge the paypal resource directly
Option 2: Authorize an amount and then charge the paypal resource

Option 1: Charge the `paypal` resource directly

Make a payments/charges POST call with the following parameters in the request body:

PayPal buyer protection
To use PayPal buyer protection, you need to create a customer resource with a shipping address.

Parameter	Required	Type	Default	Description	Example
`amount`	Yes	Number	`/`	The transaction amount.	`100.0000`
`currency`	Yes	String	`/`	The transaction currency, in the ISO 4217 alpha-3 format.	`EUR`
`returnURL`	Yes	String	`/`	The URL to redirect the customer to after the payment is completed.	`https://www.unzer.com`
`typeId`	Yes	String	`/`	The `id` of the related `paypal` resource.	`s-ppl-23ashaor54`

POST https://api.unzer.com/v1/payments/charges

Body:
{
  "amount":       "100.0000",                                    
  "currency":     "EUR",
  "returnUrl":    "https://www.unzer.com",
  "resources": {
     "typeId":        "s-ppl-23ashaor54"
   }
}


{
  "id":               "s-chg-1",
  "isSuccess":        false,
  "isPending":        true,
  "isError":          false,
  "redirectUrl":      "https://payment.unzer.com/paypal/3849234023942354935353405234320423",
    ...
}

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 where the customer completes the payment.

Option 2: Authorize and then charge the `paypal` resource

PayPal supports payment authorization.

Make a POST call to payments/authorize, with the following parameters in the request body:

Parameter	Required	Type	Default	Description	Example
`amount`	Yes	Number	`/`	The transaction amount.	`50`

POST https://api.unzer.com/v1/payments/s-pay-1/charges

{
  "amount" : "50"
}

Step 3: Forward the customer to the redirect URL

After you charge the paypal resource, implement the following flow:

Redirect the customer to the redirectURL.
The customer is forwarded to the PayPal payment page.
After a successful payment, the customer is redirected to the returnURL that you specified in the charges call (Step 2).

Step 4: Check the payment status

After the customer is redirected to the returnUrl, check the status of the payment.

Make a GET call with the following parameters in the request path:

Parameter	Required	Type	Default	Description	Example
`resource_ID`	Yes	String	`/`	The returned ID of the `paypal` resource that you created in Step 1.	`s-ppl-23ashaor54`
`transaction_ID`	Yes	String	`/`	The transaction’s unique ID that you received in Step 2.	`s-chg-1`

GET https://api.unzer.com/v1/payments/{resource_ID}>/charges/{transaction_ID}

{
    "id":                "s-chg-1",
    "isSuccess":   true,
    "isPending":   false,
    "isError":     false,
    "redirectUrl": "",
     ...
}

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.

Implement the PayPal UI on your website

Web integration
Before implementing the PayPal UI on your website, read the web integration topic.

When implementing the PayPal UI on your website, you can choose from two different UI solutions:

PayPal redirect payment without email input field
PayPal redirect payment with email input

Both options forward the customer to a dedicated payment site.

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 the script 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

To create an instance of PayPal with an email field, see redirect payments page to create a form.

Email input field
Even though you will provide a PayPal instance with the email, the input field is optional.

Create an HTML form, into which the PayPal UI will be inserted:

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

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

Localization
We support localization. You can create your HTML form in different languages.

Step 4: Create a PayPal resource

To create a new PayPal instance, call the heidelpayInstance.Paypal() method:


var Paypal = heidelpayInstance.Paypal()
Paypal.create('email', {
  containerId: 'container-example-paypal'
})

The IDs must match
Make sure that the IDs in your HTML and JavaScript files match. For more information on how to create your HTML form correctly, go to web integration.

Step 5: Create your resource ID and submit the form

Add the code that handles the form submission. These are the actions the code sample below performs:

Gets the form element by its ID.
Adds an event listener to the submit button.
Creates a Promise with .createResource and submits the form.

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
    })
});

Step 6: Review the code

View the complete code samples that you can use to implement the PayPal UI on your website.

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

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


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
    })
});

Optional: Update a PayPal resource

You can update the value of an existing PayPal resource. The update process is very similar to creating a new PayPal resource, with the following differences:

You need to pass the resourceId when calling create().
At the end, you need to run updateResource() instead of createResource().

The HTML is the same as in Step 2.


var heidelpayInstance = new heidelpay('s-pub-xxxxxxxxxx');

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
    })
});

UI reference

Constructors

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

Methods

Method	Type	Description	Returns
`create(type, options)`	void	Creates an input field for the PayPal payment method specified by the `type` parameter. Additionally, you can pass different options as key-value pairs inside the `options` parameter.	An object containing success or error details.
`addEventListener(name, paypalEventHandler)`	void	Provides an option to add a custom `eventHandler` function, which validates the email value.	An object containing success or error details.
`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,` `email: String}` Error: `{}`
`updateResource()`	Promise	Creates a Promise and submits the new data from the form. If resolved, the old `email` data is updated.	An object containing success or error details. Success: `{id: String,` `method: String,` `email: String}` Error: `{}`

`create` properties

Property	Type	Description
`type`	String	Specifies the type of input field to be created. Valid value: `email`
`options`	Object	A JSON with various options for the created input field.
`containerId`	String	The HTML `id` of the DOM element, where the UI component will be inserted. Example: `containerId: 'container-example-paypal'`
`resourceId`	String	The `id` of the created resource you wish to update. You need to pass the `resourceId` before before using the `updateResource` method.

addEventListener properties

Property	Type	Description
`name`	String	Specifies the type of the event listener. Valid values: `change`
`paypalEventHandler`	Function	Place for a custom function. It receives an object with the `success` key, which can be true or false.

`createResource` response properties

Property	Type	Description
`id`	String	The ID of the returned `/types/paypal` resource.
`method`	String	The chosen payment method.
`email`	String	Masked value of the passed email value. It will only be returned if valid email address has been passed.

`updateResource` response properties

Property	Type	Description
`id`	String	The ID of the returned `/types/paypal` resource.
`method`	String	The chosen payment method.
`email`	String	Masked value of the passed email value. It will only be returned if valid email address has been passed.