PayPal V2

This payment method is currently on a supervised rollout phase. Please contact your Technical Account Manager if you are interested by Paypal V2.

 

Reach an engaged and loyal network of more than 400 million active accounts looking to pay with PayPal.

Presentation

BrandPayment flowAPI Product CodeCountriesCurrencies3DSRefund / Partial refundRecurring
PayPalPopuppaypalWorldwideWorldwide✅ / ✅

Activation

Ask our support or your HiPay Account Manager to enable PayPal v2 for your account.

SDK setup

To get started, include the HiPay JavaScript SDK on your HTML page.


The following link exposes a global variable, HiPay, as a function to initialize the SDK with your public credentials and your configuration.

<script type="text/javascript" src="https://libs.hipay.com/js/sdkjs.js"></script>

Then, create an instance of the HiPay JavaScript SDK. You must replace HIPAY-PUBLIC-USERNAME and HIPAY-PUBLIC-PASSWORD with the public credentials of your main HiPay Account.

This instance will allow us to specify all the options and customizations related to PayPal and its button.

var hipay = HiPay({
    username: 'HIPAY-PUBLIC-USERNAME',
    password: 'HIPAY-PUBLIC-PASSWORD',
    environment: 'stage',
    lang: 'en'
});

To determine where to place the PayPal button, the SDK needs to know in which div to instantiate the button.

So first, add in your payment web page, a new div container where the PayPal  button will be displayed. Make sure that the selector div is empty. And ensure that your div has a clear ID, as we will need this ID later.

<body>
    <div id="paypal-button"></div>
</body>

Now, we need to inform the SDK that we want to instantiate a PayPal button. To do this, you have to call the create function with the first argument paypal and a second one with the configuration of your PayPal button.

// Configuration
const request = {
  amount: 32.99, // required
  currency: 'EUR', // required
  locale: 'en_US'
};

const paypalButtonStyle = {
  shape: 'rect',
  color: 'blue'
};

const options = {
  canPayLater: false,
  request: request,
  paypalButtonStyle: paypalButtonStyle,
  selector: 'paypal-button'
};

var instancePayPal = hipay.create(
  'paypal',
  options
);

At the end of this step, you should see the PayPal button appear. However, be aware that you cannot make a payment yet.

If you don’t see the PayPal button but the following screenshot, that means your account is not configured to support PayPal v2.

Please, check the Activation part to enable PayPal v2 on your account.

Payment

To ensure HiPay has the necessary informations to manage PayPal v2 transactions, you have to setup a frontend solution by using our SDK JS and a backend solution by using one of our backend SDK.

Frontend

When a customer wants to pay for an order with the PayPal payment method by clicking on the PayPal button, a PayPal popup will be shown up on the same page in order to complete the order on Paypal.

In this popup, the customer needs to login in with his PayPal account, then the popup will show a summary of this order and provide different choices to the customer he could pay for it.

Here is an exemple of this popup, once logged in :

Note that you have to inform amount and currency informations when you need to generate a PayPal button. So it's not possible to update the amount of the PayPal payment session.
If you want to display a new amount in the PayPal popup, you have to destroy and recreate the PayPal instance so it will recreate a new PayPal button.

Once the customer clicks on the Pay button in the PayPal popup, and if the order is accepted, the popup will close and here the next steps to follow to track the order to HiPay.

instancePayPal.on('paymentAuthorized', function(paypalData) {
  // Call your backend method to create the order.
  // Here, handlePayment() is just an example method.
  handlePayment(paypalData);
});

The paymentAuthorized event is triggered when the PayPal process has completed successfully. You will then receive some PayPal informations that you should pass to your backend server.

You could also implement the following events :

instancePayPal.on('paymentUnauthorized', function(error) {
  // The payment is unauthorized for some reasons.
});

instancePayPal.on('cancel', function() {
  // The customer has cancelled its payment.
});

The paymentUnauthorized event is triggered when a problem occurs during the process.

The cancel event is triggered when the customer closes the PayPal popup.

Backend

Now, you need to handle the payment on the backend. You can refer to one of these documentations :

However, for PayPal v2 transactions, you have to provide a specific parameter provider_data in your Order request.

The provider_data  parameter is a stringified object you have to build with the following property paypal_id that has the value of the PayPal order ID that could be retrieved in the sent data from your frontend.

Here is an exemple by using our PHP SDK :

<?php

$logins = [
    'login' => $credentials['private']['login'],
    'password' => $credentials['private']['password'],
];

$data = [
    'orderid' => 'POC_PAYPAL_V2_' . rand(),
    'operation' => 'Sale',
    'accept_url' => $FRONDEND_URL . '/?type=accept',
    'decline_url' => $FRONDEND_URL . '/?type=error',
    'cancel_url' => $FRONDEND_URL . '/?type=error',
    'language' => 'fr_FR',
    'custom_data' => '{"item 1":"Large Mocha Latte", "item 2":"Banana Nut Muffin"}',
    // ...
];

try {
    //Get JSON data from front-end
    $receivedData = json_decode(file_get_contents('php://input'), true);

    //Set reponse code  at 200
    http_response_code(200);

    $config = new \HiPay\Fullservice\HTTP\Configuration\Configuration([
        'apiUsername' => $logins['login'],
        'apiPassword' => $logins['password']
    ]);
    $clientProvider = new \HiPay\Fullservice\HTTP\SimpleHTTPClient($config);
    $gatewayClient = new \HiPay\Fullservice\Gateway\Client\GatewayClient($clientProvider);

    //Instantiate order request
    $orderRequest = new \HiPay\Fullservice\Gateway\Request\Order\OrderRequest();
    $orderRequest->orderid = $data['orderid'];
    $orderRequest->operation = $data['operation'];
    $orderRequest->description = $data['description'];
    $orderRequest->long_description = $data['long_description'];
    $orderRequest->accept_url = $data['accept_url'];
    $orderRequest->decline_url = $data['decline_url'];
    $orderRequest->pending_url = $data['pending_url'];
    $orderRequest->exception_url = $data['exception_url'];
    $orderRequest->cancel_url = $data['cancel_url'];
    $orderRequest->notify_url = $data['notify_url'];
    $orderRequest->language = $data['language'];
    $orderRequest->custom_data = $data['custom_data'];
    $orderRequest->payment_product = $receivedData['payment_product'];
    // Set provider_data parameter if the payment method is PayPal and if the frontend sent an orderID parameter
    if ($orderRequest->payment_product === 'paypal' && isset($receivedData['orderID'])) {
        $providerData = ['paypal_id' => $receivedData['orderID']];
        $orderRequest->provider_data = json_encode($providerData);
    }

    //Send the request order
    $transaction = $gatewayClient->requestNewOrder($orderRequest);

    $response = [
        'transaction_number' => $transaction->getTransactionReference(),
        'order_id' => $transaction->getOrder()->getId(),
        'forward_url' => (!$transaction->getReason() ? $data['accept_url'] : $data['cancel_url']),
    ];

    // This response is send to the front-end at the success of AJAX call
    echo json_encode($response);

} catch (\Exception $e) {
    $response = [
        'error_message' => $e->getMessage(),
    ];

    // This response is send to the front-end at the failure of AJAX call
    echo json_encode($response);
}

JS SDK Reference

CREATE
var instance = hipay.create('paypal', options);
NameTypeDescription

request

object

A request which includes information about the payment.

This parameter is required if your account is configured to support PayPal v2.

paypalButtonStyle

object

The PayPal button can have multiple appearances. See the PaypalButtonStyle section below for more details.

canPayLater

boolean

If true, another PayPal button will appear below the basic one in order to purchase an order in installments.

This button is only available if the order amount is between 30 and 2000 and if the currency is EUR (€).

Default is true.

selector

string

Unique div id to generate the button. 

Here is a screenshot when enabling the canPayLater parameter :

request

A request includes all information about the current payment.

NameTypeDescription

amount

required

number

The order amount which will be displayed in the PayPal popup.

It must be greater than zero, and can contain a maximum of 2 decimal places.

currency

required

stringThe three-letter ISO 4217 currency code for the payment.
localestring

The locale code to use for the label of the PayPal button.
Example: en_US

Default is a locale based on the HiPay instance language.

paypalButtonStyle

This configuration customizes the PayPal button appearance which includes a shape, a color, a label and a height.

NameTypeDescription
shape
string

The shape of the PayPal button : pill or rect.

Default is pill.

color
string

The color of the PayPal button : goldblueblacksilver or white.

Default is gold.

label
string

The label of the PayPal button : paypaypalsubscribecheckout or buynow.

Default is pay.

height
number

The height of the PayPal button.
Minimum : 25
Maxiumum : 55

Default is 40.

EVENTS

instance.on(‘event’, callback)

Name


Description


Response

paymentAuthorized

Emitted when the user has validated the payment inside the PayPal popup.

paypalData : object

paymentUnauthorized

Emitted when an error occured during the process in the PayPal popup.

 error : object

cancel

Emitted when the user clicks on the cancel button of the PayPal popup.