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.
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".
Open a website source code.
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>
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;
var options = {
creditAmount: value, // amount in PLN
posId: '00000', // point of sale identifier
key: 'a0', // 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 and parameters described in 'Additional integration metods' section
})
.catch(function(e) {
console.error(e.toString()); // This snippet writes config errors
// to developer’s console
});
</script>
Save changes.
Refresh the website in your browser.
Parameters available in the panel.
| Parameter | Default value | Required | Description |
|---|---|---|---|
| creditAmount | none | yes | Purchase value should be in correct range – check the range for PayU | Installments payment method on page Installments and Pay later. If amount is out of given range widget will not be presented. |
| 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 and
verify if the creditAmount is in correct range - check the range
for PayU | Installments payment method on page Installments and Pay later.
OpenPayu.Installments.miniInstallment function returns a
Promise with resolved result object. Structure of a result
object is presented in a table below.
| Parameter | Type | Required | Description |
|---|---|---|---|
| isWidgetAvailable | boolean | yes | true, when input parameters allow to display
widget. Otherwise false, when for example credit
amount is out of correct range - check the range for PayU |
Installments payment method on Installments and Pay later page. |
| element | HTMLElement | available, when isWidgetAvailable = true |
DOM element containing text with installment amount and link opening popup with installments details. |
| openWidget | function | available, when isWidgetAvailable = true |
Function displays installment details popup. |
Usage of element object
OpenPayU.Installments.miniInstallment('', options)
function invocation, in a Promise callback the
element object is available for usage. The
element object is a DOM element containing text with
installment amount and link opening popup with installments details.element object is also available when selector argument in
OpenPayU.Installments.miniInstallment function is empty
(undefined, null or "").
In that case you need to display element in your own scripts.element object is available only when
isWidgetAvailable equals true. Before
object usage check if condition is fulfilled.isWidgetAvailable parameter equals
false.Example of code snippet showing element object usage:
<p><span id="installment-mini"></span></p>
<script type="text/javascript">
var value = 1234.56;
var options = {
creditAmount: value, /// amount in PLN
posId: '00000', // point of sale identifier
key: 'a0', // first two characters of API key
showLongDescription: false
};
OpenPayU.Installments.miniInstallment('', options) // selector is not required
.then(function(result) {
if (result.isWidgetAvailable) { // check if widget is available
const customText = document.createElement('span');
customText.innerText = 'PayU installments from: ';
document.getElementById("installment-mini").append(customText);
document.getElementById("installment-mini").append(result.element); // element can be appended to any html element on page
}
})
.catch(function(e) {
console.error(e.toString()); // This snippet writes config errors
// to developer’s console
});
</script>
Display installment details popup manually
OpenPayU.Installments.miniInstallment('', options) function invocation, in
a Promise callback the openWidget() function is available for usage. The
function allows to display installment details popup. OpenWidget() function is available when isWidgetAvailable equals true. Before
function invocation check if condition is fulfilled.openWidget() function will
be attached in case when isWidgetAvailable parameter equals false.undefined,
null or "") to OpenPayU.Installments.miniInstallment function.Example of code snippet allowing to open widget popup on image click:
<img id="payuLogo" src="https://poland.payu.com/wp-content/themes/global-website/assets/src/images/payu-logo.svg" hidden/>
<script>
var options = { creditAmount: 2200, posId: '00000',key: 'a0' };
window.OpenPayU.Installments.miniInstallment("", options)
.then(function (result) {
if (result.isWidgetAvailable) {
document.querySelector("#payuLogo").removeAttribute("hidden"); // display element
document.querySelector("#payuLogo").onclick = function() { result.openWidget(); }; // handle onclick action
}
})
.catch(function(e) {
console.error(e.toString());
});
</script>
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" for
Pay Later with Twisto and "dpts" for Twisto Pay in 3..
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. Twisto Pay in 3 enables the buyer to make a payment in 3 parts.
Pay later with Twisto and Twisto Pay in 3 are "credit-type" payment methods, 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 and Twisto Pay in 3 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, dpts | 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 and Twisto Pay in 3 are also available on the sandbox environment. When you process these pay methods 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 Twisto payment methods are not a default payment methods - 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 or Twisto Pay in 3 payment method for you.
Step 4
Send your order via the REST API on a newly created POS (existing POS will not have these paymethods added). Select Pay Later with Twisto or Twisto Pay in 3 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.
