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:

  1. Redirect the customer to the redirectURL.
  2. The customer is forwarded to the PayPal payment page.
  3. 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:

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:

  1. Gets the form element by its ID.
  2. Adds an event listener to the submit button.
  3. 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.