payMethod(OpenPayU) or pay_type(NewPayment) parameter is "ai".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.
The process has been showcased on the diagram below.
Once the transaction has been confirmed manually (or automatically collected), the buyer is informed about the outcome of loan request processing.
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.
PayU makes it possible to enable or disable the automatic receipt in a POS.
If Automatic collection has been enabled, transactions are processed automatically, without manual confirmation.
If Automatic collection has been disabled, transactions are processed only after they have been manually confirmed.
To manually confirm a transaction in the Management Panel when Automatic collection is disabled:
Information about transaction support via API is available in the Information exchange.
Automatic collection can be configured as other standard payment methods.
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:
The above elements help enjoy the following benefits:
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.
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.
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.
The calculator of PayU Installments allows for a convenient analysis of options of repaying the installments. A customer adjusts the value and the number of installments using bars, thus receiving an installment rate. It is possible to include insurance when calculating the installment rate.
Step 1
Open a website source code and make sure it uses utf-8 encoding (calculator was written specifically for this encoding).
Installment widgets use internally jquery libraries and allow simultaneous use of other versions. For example, including widget-calculator-installments.min.js file to a client's site does not override other jquery scripts and is used only by widgets internally.
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.
<meta charset="utf-8" />
<script src="https://static.payu.com/res/v2/widget-calculator-installments.min.js"></script>
<link href="https://static.payu.com/res/v2/layout/style.css" rel="stylesheet">
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.
This element will feature a 712x402px calculator.
<div id="installment-calc"></div>
<script type="text/javascript">
var openpayu = openpayu || {};
openpayu.options = {
creditAmount: 4234.56, // amount in PLN
posId: '67328', // point of sale identifier
key: 'zQ' // first two characters of API key
};
OpenPayU.Installments.calculator('#installment-calc');
</script>
Step 4
Save changes.
Step 5
Refresh the website in your browser.
Parameters available in the panel| Parameter | Default value | Required | Description |
|---|---|---|---|
| posId | none | yes | Point of sale identifier posId. |
| key | none | yes |
Key dependent on the point of sale type. For:
|
| interestRate | 6.5 | no | The value must comply with an agreement signed by the shop and PayU. |
| installmentAmount | 3 | no | Number of installments in the range 3 to 36. |
| installmentMinAmount | 3 | no | Minimum number of installments. |
| installmentMaxAmount | 36 | no | Maximum number of installments. |
| creditMinAmount | 300 | no | Lowest purchase value. |
| creditMaxAmount | 20000 | no | The highest purchase value. |
| creditAmount | 300 | no | Purchase value in the range PLN 300 to PLN 20,000. |
| 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.
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.
<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.
<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:
|
| showLongDescription | false | no | Once activated, the specific prefix will be added. For languages:
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.
payMethod parameter is "dpt".payMethod parameter is "dpp".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.
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.
payMethod parameter is
"dpcz".
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.
In this section, described examples are in OpenPayU protocol. Pay Later with Twisto is available for PayU HUB merchants.
| 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 |
| 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 |
| Buyer's email address. | Yes | |
| buyer.delivery | Section containing delivery address. For a list of parameters, see section <buyer.delivery>. | No, recommended |
| 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 |
| Parameter | Description | Required |
|---|---|---|
| name | Name of the product | Yes |
| unitPrice | Unit price | Yes |
| quantity | Quantity | Yes |
| Parameter | Description | Required |
|---|---|---|
| type | Payment method type: PBL | Optional |
| value | Twisto payment value: dpcz | Optional (if it is sent, payment wall is not presented) |
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"
}
]
}'
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.
