PayU is an operator of online payments some times called "an e-commerce gateway". Payments made through them are different from ordinary transfers in that the recipient receives money much faster, because they are made through one bank.
The process of handling payments in the online store via the PayU service consists of two stages.
Performing system integration can be carried out in many ways made available by PayU, such as: REST API, Classic API, SDK, PayU | PayTouch, Payout API.In addition, many store platforms offer built-in integration with PayU, but in the case of jPalio™ this is not necessary because it contains unique methods that greatly facilitate this process.
If we decide to integrate ourselves in jPALIO™, we must first choose how we will do it, here the recommended method is REST API. Then authentication. There are two methods of user authentication via the API: OAuth (recommended) and HTTP Basic.
OAuth authentication consists in retrieving a token. It is used in further communication with PayU servers and we create an order based on it. Here comes the API or integration of the order form, however, integration through the form is not recommended and presented only for information purposes for existing implementations. Most of the information provided is in JSON format.
Another thing is servicing the status of the order, which allows us to end the transaction or the looping at the time of failure. Thanks to the use of jPALIO™, we can independently modify errors, which allows us to have complete freedom and implement new solutions.
PayU gives us a lot of space to get in touch with it. Sandbox and 2 test servers are available. Starting from the communication with the server we have the ability to listen to the server to which we send requests, which are compared with the documentation and make it much easier to detect the error. For this purpose, it is also recommended to use the Postman program, which will allow us to bypass problems in the code and test the query itself, which gives us the opportunity to quickly detect the error. On the other hand, Sandbox gives us the opportunity to perform payment tests without any embarrassment.
package api.payU.config;
import palio.*
import palio.modules.*
// Przed konfiguracją API PayU zapoznaj się z README (api.payU.README).
public class Configuration {
private static final Net net = Groovy.module("net")
// Parametry konfiguracyjne
// Parametry wymagane opisane w README (api.payU.README) w UWAGI.
private static String client_id = "3223230"
private static String merchantPosId = "322230"
private static String client_secret = "377q6e7r6ra77bf75aa6345f9247"
private static String customerIp = net.getClientIP()
private static String hostUrl = "https://secure.snd.payu.com"
// Przekazywane parametry body. Trafia do POSTA w api.payU.PayUController getAccessToken().
// Ku przestrodze. Poniższy format jest błedny i nie za każdym razem zostaje poprawnie odczytany.
// '''
// {
// "grant_type": "client_credentials",
// "client_id": "300746",
// "client_secret": "2ee86a66e5d97e3fadc400c9f19b065d"
// }
// '''
public static String getAccessTokenBodyParam (){
return ("grant_type=client_credentials&client_id=${client_id}&client_secret=${client_secret}")
}
// Przekazywane parametry body. Trafia do POSTA w api.payU.PayUController createOrder().
public static String getOrderBodyParam (){
return ('''
{
"customerIp": "127.0.0.1",
"merchantPosId": '''+merchantPosId+''',
"description": "RTV market",
"currencyCode": "PLN",
"totalAmount": "21000",
"buyer": {
"email": "john.doe@example.com",
"phone": "654111654",
"firstName": "John",
"lastName": "Doe",
"language": "pl"
},
"products": [
{
"name": "Wireless Mouse for Laptop",
"unitPrice": "21000",
"quantity": "1"
}
]
}
''')
}
// Ustawia url hosta na który zostaja wysyłane metody POST, GET.
public static String getHostUrl (){
return hostUrl
}
}
INTEGRATION FLOW
In this paragraph You can find most popular payments flows.standard payment flow
1. obtain access token (client_credentials or trusted_merchant)
2. send order create request using received access token
3. redirect client to received link
NOTE
Specify prices using the lowest currency unit e.g. in lowest currency unit for PLN, so 1000 is equal to 10 PLN.
HUF is the exception – multiply this by 100.Note: specify prices using the lowest currency unit e.g.
in lowest currency unit for PLN, so 1000 is equal to 10 PLN. HUF is the exception – multiply this by 100.
Parameter Description Required
customerIp Customer IP address Yes
merchantPosId Point of sale ID Yes
description Description of the an order Yes
currencyCode Currency code (e.g PLN, EUR) 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
recommended
buyer Section containing buyer data.
This information is not required, but it is strongly recommended to include it.
Otherwise the buyer will be prompted to provide missing data on PayU page and payment
via installments or delayed payments will not be possible.
For a list of parameters, see section <buyer> No
EXPLANATION
You authenticate with OAuth standard by obtaining a token, which is used for further communication with PayU servers.
You can veiw authorization data from the management panel. There are two grant types: client_credentials
for standard integration (for standard integration) and trusted_merchant (for use with token payments).
IMPLEMENTATION
Create a PayUDao file that will allow communication between the site and the database.
In order to check the correctness of the code, you can create a page with the object and the content:
$ // $ * portal.model.beans.invokeStaticMethod ("api.payU.PayUController", "createTokeAndOrder", null)
and then turn on the page in the browser, the effect of acceptance should be redirecting to the PayU website.
An example of a correct implementation can be found on the jerb.bibula.pl instance bibula_b2b.
Most of the changes that must be made will be found in the Configuration file (api.payU.config.Configuration).
Scripts for creating arrays in databases can be found in the sqlScripts (api.payU.config.sqlScripts) file.
Set your data in the api.payU.PayUController getAccessToken () for example
Payment type (grant_type): client_credentials
OAuth protocol (client_id): 300746
OAuth protocol (client_secret): 2ee86a66e5d97e3fadc400c9f19b065d
Change the url on which POST is sent to this from PayU (in case of testing for a server that we can listen to or a sandbox)
in api.payU.PayUController httpPostPayU (), getAccessToken (), createOrder () e.g.
httpPostPayU ("https://private-anon-81288937ba-payu21.apiary-mock.com/us/standard/user/oauth/authorize", ..., ...)
DESCRIPTION
<product> fields description
Parameters Description Required
name Name of the product Yes
unitPrice Unit price Yes
quantity Quantity Yes
virtual Product type, which can be virtual or material; (possible values true or false). No
listingDate Marketplace date from which the product (or offer) is available, for example: "2016-01-26T17:35:37+01:00" No
<buyer> section fields description.
Parameter Description Required
customerIp Customer's IP address No
extCustomerId ID of the customer used in merchant system No
email Buyer's email address Yes
phone Buyer's telephone number No
firstName Buyer's first name No
lastName Buyer's last name No
nin National Identification Number No
language Denotes the language version of PayU hosted payment page and of e-mail messages sent from PayU to the payer (supported values are here) No
buyer.delivery Section containing delivery address. For a list of parameters, see section <buyer.delivery> No
<buyerDelivery> fields description
Parameter Description Required
street Street Yes
postalBox Postal box No
postalCode Postal code Yes
city city Yes
state State No
countryCode Country code Yes
name Address description No
recipientName Recipient name Yes
recipientEmail Recipient email No
recipientPhone Recipient phone number No
<order> fields description
Parameter Description
orderId Order ID generated by the PayU system
extOrderId External order ID (assigned by the shop)
orderCreateDate Order creation timestamp
notifyUrl Address for sending notifications
customerIp Customer's IP address
merchantPosId Point of sale ID
description Description for order
validityTime Duration for the validity of an order (in seconds), during which time payment must be made
currencyCode Currency code (e.g PLN, EUR)
totalAmount Total price of the order
buyer Section containing buyer data. For a list of parameters, see section <buyer>
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>
<status> section fields description
Parameter Description
statusCode Response code
statusDesc Response status description
ENDPOINT PATHS
Address HTTP Method Comment Full reference
/pl/standard/user/oauth/authorize POST Provides OAuth token. Signing API calls
api/v2_1/paymethods POST Provides available payment methods. Payment methods retrieval
/api/v2_1/orders POST Creates Order and enables to initiate payment transaction. OrderCreateRequest
/api/v2_1/orders/{orderId} GET Provides Order data and status. OrderRetrieveRequest
/api/v2_1/orders/{orderId} DELETE Cancels Order. Canceling Order
/api/v2_1/orders/{orderId}/transactions GET Provides payment transaction details (bank account details or card data). Transaction data retrieval
/api/v2_1/orders/{orderId}/status PUT Captures Order. Order capture
/api/v2_1/orders/{orderId}/refunds POST Allows to perform refunds (total or partial) Refund
/api/v2_1/payouts POST Allows to request payout directly from your application (note: automated or ad hoc payouts are also available in the Panel) Payouts
api/v2_1/mcp-partners/{mcpPartnerId}/fx-table GET Provides available currency pairs. Multi-Currency Pricing
/api/v2_1/reports/{reportId} GET Allows to download transaction statement (note: automated or ad hoc statements are also available in the Panel). Visa Checkout
/api/visa-checkout/proxy/payment/data/{callId} GET Allows to download data (card number, shipping address etc.) from Visa Checkout. Visa Checkout
USEFUL LINKS
REST API 2.1 for the PayU payment system.
https://payu21.docs.apiary.io/#
Listening to the PayU server.
https://payu21.docs.apiary.io/traffic
Status codes from PayU.
http://developers.payu.com/pl/restapi.html#references_statuses
Parameters of JSON messages.
http://developers.payu.com/pl/restapi.html#references_api_parameters
Sandbox PayU.
http://developers.payu.com/pl/overview.html#sandbox
List of endpoints.
http://developers.payu.com/pl/overview.html#endpoint_reference
PayU technical support.
tech@payu.pl