payu integration

PayU - Introduction to the implementation of payments in the online store.

 

What is the PayU?

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.

Payment process.


The process of handling payments in the online store via the PayU service consists of two stages.

In the first stage a buyer placing an order.
  • The buyer clicks on the button representing the PayU payment service.
  • The PayU system presents a page with a summary of the order at which the buyer confirms the payment. The PayU system redirects the buyer to the bank's website.
  • The buyer accepts the payment on the Bank's website. The buyer is redirected to the PayU website again.
  • The Seller's system presents payment information and thank you for completing the transaction.

 

Second stage (optional). Settlement (collection) of payment.
  • The PayU system notifies the seller's system of changing the status of the payment processed by means of notifications.
  • The seller's system confirms that the notification has been received.

 

Integration of PayU with jPALIO.

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.

 

Testing.


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.

 

An example of jPALIO™ Groove PayU service configuration object $*api.payU.config.Configuration

 




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
	}


}

 

An example of jPALIO™ PayU service configuration README object $*api.payU.config.README

 


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
 


Return