Installments and Pay later

1 PayU | Installments

1.1 Introduction

Basic information

  • PayU | Installments are available for merchants free of charge.
  • PayU | Installments are available for shopping carts worth PLN 300 to PLN 50,000.
  • The service can be integrated via OpenPayU (REST API) or NewPayment (Classic API) protocol.
  • The value of payMethod(OpenPayU) or pay_type(NewPayment) parameter is "ai".

Service description

These guidelines aim to present ways of implementing PayU | Installments in an e-shop. The document is mainly dedicated to developers.

The procedure of processing payments in the PayU | Installments service in an e-shop consists of two stages.

  1. A buyer places an order on an e-shop webpage.
  2. PayU confirms that the payment has been settled correctly.

First stage. A buyer places an order.

The process has been showcased on the diagram below.

  1. Buyer clicks on a button that represents PayU | Installments.
  2. If payMethod/pay_type=ai, name and surname are not stated,PayU system presents an order summary webpage, where the buyer confirms the payment.
  3. PayU system redirects the Buyer to the website of a loan partner.
  4. Buyer performs actions required by the loan partner, e.g. accepts an offer or makes a verification transfer.
  5. Loan partner confirms to PayU that it has processed the payment and redirects the buyer back to the PayU website.
  6. At this stage, a transaction may receive one of three statuses depending on the loan partner's decision or ability to consider the installments request:
    1. If the loan partner is not able to verify all the details of or process the loan request right away, the transaction status is set to PENDING. The buyer is then redirected to a PayU webpage, which contains information that the request has received the PENDING status and a button to return to the shop.
    2. If a loan has not been granted or the loan partner is not able to process the loan request, the transaction status is set to FAIL, and the buyer is redirected to a page indicated in the shop configuration as a negative URL.
    3. Once the loan request has been considered and the loan has been granted, the transaction status is set to SUCCESS and the buyer is redirected to a page indicated in the shop configuration as a positive.
  7. PayU system redirects the buyer to a page in the seller’s system, which informs the buyer that the order has been placed successfully.
Once the transaction has been confirmed manually (or automatically collected), the buyer is informed about the outcome of loan request processing.

Second stage (optional). Payment settlement.

  1. PayU system notifies the seller’s system that a status of the payment order has changed.
  2. Seller’s system confirms receiving the notification.

1.2 Integration

In this section, described examples are in OpenPayU protocol, Raty PayU are also available in Classic API protocol.

Example of inegration via form. OpenPayU protocol:

                <form method="POST" action="https://secure.payu.com/api/v2_1/orders">
                    <input type="hidden" name="customerIp" value="123.123.123.123">
                    <input type="hidden" name="merchantPosId" value="145227">
                    <input type="hidden" name="description" value="Order description">
                    <input type="hidden" name="totalAmount" value="99900">
                    <input type="hidden" name="currencyCode" value="PLN">
                    <input type="hidden" name="products[0].name" value="Notebook">
                    <input type="hidden" name="products[0].unitPrice" value="99900">
                    <input type="hidden" name="products[0].quantity" value="1">
                    <input type="hidden" name="notifyUrl" value="http://shop.url/notify" >
                    <input type="hidden" name="continueUrl" value="http://shop.url/continue" >   
                    <input type="hidden" name="payMethods.payMethod.type"  value="PBL" > 
                    <input type="hidden" name="payMethods.payMethod.value" value="ai" >                                 
                    <input type="hidden" name="OpenPayu-Signature" type="hidden" value="sender=145227;algorithm=SHA-256;signature=a9d91ae1f3fc26aba5b9600ffeb734e6c5fcd6346eb3f9dc5e43d8b29c04d2e8">
                    <button type="submit" formtarget="_blank">PayU</button>
                </form>
            

POS used in the example does not have installments switched on. Therefore Buyer won't be redirected to aplication form, PayU syatem presents summary page. More information about form parameters described in: Creating a new order.

Order example via REST API with one product, basic Buyer data and extOrderId:

curl -v -X POST https://secure.payu.com/api/v2_1/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
-d '{
    "notifyUrl": "https://your.eshop.com/notify",
    "customerIp": "127.0.0.1",
    "merchantPosId": "145227",
    "description": "RTV market",
    "currencyCode": "PLN",
    "totalAmount": "99900",
    "extOrderId":"[generateExtOrderId]",
    "buyer": {
         "email": "jan.kowalski@example.com",
         "phone": "654111654",
         "firstName": "Jan",
         "lastName": "Kowalski"
     },
     "payMethods":{
         "payMethod":{
              "type":"PBL",
              "value":"ai"
          }
     },
     "products": [
          {
               "name": "Laptop",
               "unitPrice": "99900",
               "quantity": "1"
          }
      ]
}'
                
Authentication methods are described in: Signing API calls parameters.

POS used in the example does not have installments switched on. Therefore Buyer won't be redirected to aplication form, PayU syatem presents summary page. More information about REST API parameters described in: Creating a new order.

Style the form to have the PayU | Installments well identified.

<style type="text/css">
form[name="payform"] input[type="submit"] {
    border: 0px;
    height: 35px;
    width: 100px;
    background: url('http://static.payu.com/pl/standard/partners/raty_payu/raty_small.png');
    cursor: pointer;
}
</style>
                    

Save changes in the file and reload the page in your browser.

1.3 Automatic collection

PayU makes it possible to enable or disable the automatic receipt in a POS.

Automatic collection enabled

If Automatic collection has been enabled, transactions are processed automatically, without manual confirmation.

Automatic collection disabled

If Automatic collection has been disabled, transactions are processed only after they have been manually confirmed.

Manual transaction confirmation

To manually confirm a transaction in the Management Panel when Automatic collection is disabled:

  1. Go to the Management Panel.
  2. Go to Transactions --> List of transactions. .
  3. In the Status field, select Waiting for collection. Optionally, set other search parameters.
  4. Click on Show.
  5. To confirm the transaction, in the Action column, click on Collect.
  6. Check if data is correct and click on OK.

Information about transaction support via API is available in the Information exchange.

Configuring Automatic collection

Automatic collection can be configured as other standard payment methods.

1.4 How to promote

1.4.1 Introduction

The goal of each e-business is to present a comprehensive and innovative offer to customers. By introducing PayU | Installments, a shop may achieve this goal by presenting information on the new service in a simple and clear way.

This section describes a manner of introducing the following elements:

  1. elements building graphic identification, such as buttons or static banners,
  2. installment widget
  3. calculator widget.

The above elements help enjoy the following benefits:

  1. professional approach to e-shop customers;
  2. relevant amount of information about shopping on installments;
  3. keeping customers interested, thus increasing the number of successful transactions;
  4. allowing customers to make quick payments;
  5. encouraging satisfied customers to return to the e-shop.

1.4.2 Graphic identification

Sign “Here you can pay via PayU | Installments”

In order to inform a customer that you offer shopping on installments, we recommend adding the “Here you can pay via PayU | Installments” button on the main page or on other e-shop pages

A customer who clicks on the button is redirected to the informational PDF document about PayU Installments.

To produce this effect on your shop website, enter the following code:

<a href="http://www.payu.pl/en/payu-installments-for-business">
    <img src="http://static.payu.com/pl/standard/partners/raty_payu/tu_kupisz_na_raty_payu_blue.png" />
</a>
            

Other graphic versions are available here.

Transaction button

To draw your customer’s attention to quick installment shopping, use the following button

To produce this effect on your shop website, style the form button using the following code between the <head> tags:

<style type="text/css">
form[name="payform"] input[type="submit"] {
    border: 0px;
    height: 35px;
    width: 100px;
    background: url('http://static.payu.com/pl/standard/partners/raty_payu/raty_small.png');
    cursor: pointer;
}
</style>
            

Other graphic versions are available here.

Static banners

We have also designed static graphical ads which you can use to inform customers that PayU | Installments are available in your shop.

Other graphic versions are available here.

1.4.3 Widget Installments

In order to inform a customer about the lowest installment value for a given product, we recommend adding an installment widget to a products list, a product card, a shopping cart and in the checkout. In case of the products list (including few widgets), remember about unique identifiers for the widgets. A good solution is to determine an id on a product id. For example, for a product with id 3241 id="installment-mini-3241".

Step 1

Open a website source code.

Step 2

Paste the following script in the <head> section. Please note: do not copy this script to your server, because PayU scripts contain the information about current settings for installments.

Example
<meta charset="utf-8" />
<script src="https://static.payu.com/res/v2/widget-mini-installments.js"></script>
                    

Step 3

Paste the following code, after editing creditAmount, posId (enter your data) and key (enter your data) in the <body> section of your source code.

Example
<p><span id="installment-mini"></span></p>
<script type="text/javascript">
    var value = 1234.56;
    if (value >= 300 && value <= 50000) {
        var options = { 
            creditAmount: value,    // amount in PLN 
            posId: '67328',         // point of sale identifier 
            key: 'zQ',              // first two characters of API key
            showLongDescription: true 
        }; 
    
        OpenPayU.Installments.miniInstallment('#installment-mini', options) 
        .then(function(result) { 
            // This fragment of code will be executed after widget is shown  
            // parameter ‘result’ contains additional functions
        }) 
        .catch(function(e)  { 
            console.error(e.toString()); // This snippet writes config errors
            // to developer’s console
        });
    }
</script>      
                    

Step 4

Save changes.

Step 5

Refresh the website in your browser.

Parameters available in the panel.
Parameter Default value Required Description
creditAmount none yes Purchase value in the range PLN 300 to PLN 50,000.
posId none yes Point of sale identifier posId. Identifier contains only digits.
key none yes Key dependent on the point of sale type. Key contains digits or lowercased characters a-f. For:
  • REST API - first two characters of "OAuth protocol - client_secret"
  • Classic API - first two characters of "Key (MD5)"
showLongDescription false no Once activated, the specific prefix will be added. For languages:
  • pl (default), Rata już od:
  • en, Installment from:
It is recommended to iniatiate value with a true value. Regarding future product changes it will be automatically updated.
currencySign PLN no Currency
lang pl no Language used in the component. Available values: en, pl.
If you cannot see any changes despite refreshing the page, try to clear cache.

2 PayU Pay later (Poland)

2.1 Available payment methods

Twisto | PayU Pay later

  • Twisto | PayU Pay later is available for shopping carts worth from 1 PLN to 1500 PLN.
  • The service has to be integrated via OpenPayU (REST API) protocol.
  • The value of payMethod parameter is "dpt".

PayPo | PayU Pay later

  • PayPo | PayU Pay later is available for shopping carts worth from 10 PLN to 2000 PLN.
  • The service has to be integrated via OpenPayU (REST API) protocol.
  • The value of payMethod parameter is "dpp".

Service description

PayU Pay later enables the buyer pay for ordered goods within 30 days without any additional costs. After the mentioned period of time, customer can split their payment into installments.

The procedure of processing payment and automatic collection for PayU Pay later regarding e-shop integration is the same as for the service PayU | Installments.

Additional Information

When integrating with the OpenPayU protocol (REST API) in order to use the service PayU Pay later, it is recommended to send the completed section credit in the OrderCreateRequest message. Sending this data significantly simplifies and speeds up the process on the user's side. The credit section is not required, but its use is recommended for the best possible conversion.

3 Pay Later with Twisto (Czech)

3.1 Introduction

Basic Information

  • Pay Later with Twiso is available on Czech market for a group or verticals.
  • Merchant has to sign an annex and go through additional verification, before this payment method can be turned on.
  • This service is not available on SDK.
  • The value of payMethod parameter is "dpcz".
  • Having Twisto pay button separated at checkout (instead of using PayU paywall), a mandatory active link “Použitím služby Twisto Pay souhlasíte s obchodními podmínkami” must be added next to the Twisto pay button or in another clearly visible place at checkout. It will redirect the buyer to Twisto pay Terms & Condition (stored and updated by Twisto), similarly to mandatory link presented by PayU on PayU paywall (see an example below).

Service description

Pay later with Twisto enables the buyer to make a payment for ordered goods within 30 days without any additional costs. Mechant gets money within 2 working days from transaction acceptance.

Pay later with Twisto is "credit-type" payment method, so final decision depends on user scoring.

Partial and full refunds are fully supported via PayU system.

3.2 Payment Processing

In this section, described examples are in OpenPayU protocol. Pay Later with Twisto is available for PayU HUB merchants.

Request parameters description

Parameters Description Required
customerOp Payer’s IP address, e.g. 123.123.123.123. Note: 0.0.0.0 is not accepted. Yes
merchantPosId Point of sale ID. Yes
description Description of the an order. Yes
CurrencyCode Currency code compliant with ISO 4217 (e.g EUR). Yes
totalAmmount Total price of the order in pennies (e.g. 1000 is 10.00 CZK). Yes
buyer Section containing buyer data. For a list of parameters, see section <buyer>. Yes
products Section containing data of the ordered products. Section products is an array of objects of type <product>. For a list of parameters, see section <product>. Yes
payMethods Section allows to directly invoke payment method. Section <payMethods> is one object of <payMethods> type. For a list of parameters, see section <payMethods>. No

<buyer> section fiedls description

Parameter Description Required
firstName Buyer's first name. Yes
lastName Buyer's last name. Yes
phone Buyer's phone number. Phone number must be sent with country code "+420" and recommended phone validation library is here. Yes
email Buyer's email address. Yes
buyer.delivery Section containing delivery address. For a list of parameters, see section <buyer.delivery>. No, recommended

<buyer.delivery>

Parameter Description Required
recipientName Buyer's first name. No, recommended
recipientPhone Buyer's phone number. Phone number must be sent with country code "+420" and recommended phone validation library is here. No, recommended
Street Street No, recommended.
countryCode Two-letter country code compliant with ISO-3166. No, recommended
postalCode Postal code. No, recommended
city City name. No, recommended

<product> section fields description

Parameter Description Required
name Name of the product Yes
unitPrice Unit price Yes
quantity Quantity Yes

<payMethod> section fields description

Parameter Description Required
type Payment method type: PBL Optional
value Twisto payment value: dpcz Optional (if it is sent, payment wall is not presented)

Order example via REST API with one product, basic Buyer data and extOrderId:

                curl -v -X POST https://secure.payu.com/api/v2_1/orders \
                    -H "Content-Type: application/json" \
                    -H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
                    -d '{
                        "notifyUrl": "https://your.eshop.com/notify",
                        "customerIp": "127.0.0.1",
                        "merchantPosId": "145227",
                        "description": "RTV market",
                        "currencyCode": "CZK",
                        "totalAmount": "99900",
                        "extOrderId":"p0ruyvh4dx4ymzifoexy0o",
                        "buyer": {
                            "email": "jan.kowalski@example.com",
                            "phone": "+420123456789",
                            "firstName": "Jan",
                            "lastName": "Kowalski",
                            "delivery": {
                                "recipientName": "Jan Novak",
                                "recipientPhone": "+420123456789",
                                "street": "Antala Staska 2027/77",
                                "postalCode": "14000",
                                "city": "Praha",
                                "countryCode": "CZ" 
                            }
                        },
                        "payMethods":{
                            "payMethod":{
                                "type":"PBL",
                                "value":"dpcz"
                            }
                        },
                        "products": [
                            {
                                "name": "Laptop",
                                "unitPrice": "99900",
                                "quantity": "1"
                            }
                        ]
                    }'
            

3.3 Sandbox testing

Pay Later with Twisto is also available on the sandbox environment. When you process Pay Later with Twisto on sandbox, your data will be validated and you can verify integration.

Follow the steps described below in order to test.

Step 1

Create an account on sandbox environment, in case you don't have one - register, and activate your account.

Step 2

Login to your account - login page , and note your sandbox Company ID.

Step 3

Since Pay Later with Twisto is not a default payment method - please, contact us in order to activate it. In your request send your sandbox Company ID. PayU will create a shop and POS with the Pay Later with Twisto payment method for you.

Step 4

Send your order via the REST API on the created POS. Select Pay Later with Twisto on the Payu Paywall when applicable and you will be redirected to the Twisto simulator.

Step 5

On the Twisto simulator page Payu will present any validation problems with your order. Fix the errors to continue, and you will be able to authorize the payment. Exemplary validation result is presented below.