intergacja z payu

PayU - Wstęp do Implementacji płatności w sklepie internetowym.

Czym jest PayU?

PayU jest operatorem płatności internetowych- wpłaty dokonane za ich pośrednictwem różnią się od zwykłych przelewów tym, że odbiorca otrzymuje je dużo szybciej, gdyż dokonywane są za pośrednictwem jednego banku.

 

Proces obsługi płatności.


Proces obsługi płatności w sklepie internetowym za pośrednictwem usługi PayU składa się z dwóch etapów.

Etap pierwszy to złożenie zamówienia przez kupującego.
  • Kupujący klika w przycisk reprezentujący usługę płatności PayU.
  • System PayU prezentuje stronę z podsumowaniem zamówienia, na której kupujący potwierdza płatność. System PayU przekierowuje kupującego na stronę banku.
  • Kupujący akceptuje płatność na stronie Banku. Następuje przekierowanie kupującego ponownie na stronę systemu PayU.
  • System Sprzedawcy prezentuje podziękowanie za transakcje.

 

Etap drugi (opcjonalny). Rozliczenie (odebranie) płatności.
  • System PayU powiadamia system sprzedawcy o zmianie statusu procesowanej płatności zgodnie z jej cyklem za pomocą powiadomień ("notyfikacji").
  • System sprzedawcy potwierdza odebranie powiadomienia.

 

Integracja PayU z jPALIO™.


Przeprowadzanie integracji systemu można przeprowadzić na wiele sposobów udostępnionych przez PayU, takich jak: REST API, Classic API, SDK, PayU | PayTouch, Payout API. Ponadto, wiele platform sklepowych oferuje wbudowaną integrację z PayU, jednak w przypadku jPALIO™ nie jest to konieczne, ponieważ zawiera unikalne metody znacznie ułatwiające ten proces.


Jeżeli zdecydujemy się na własną integrację w jPALIO™, musimy na początku wybrać w jaki sposób jej dokonamy, tutaj rekomendowanym sposobem jest REST API. Następnie uwierzytelnienie. Możliwe są dwie metody uwierzytelnienia użytkownika przez API: OAuth (rekomendowana) oraz HTTP Basic.

Uwierzytelnienie OAuth polega na pobraniu tokena. Jest on używany w dalszej komunikacji z serwerami PayU i na jego podstawie tworzymy zamówienie. Tutaj wkracza API lub integracja formularza zamówienia jednak integracja poprzez formularz nie jest zalecana i prezentowana jedynie w celach informacyjnych dla istniejących implementacji. Większość przekazywanych informacji jest w formacie JSON.

Kolejną rzeczą jest obsługa statusów zamówienia, która pozwala nam na zakończenie przebiegu transakcji bądź zapętlenie w momencie niepowodzenia. Dzięki wykorzystaniu jPALIO możemy samodzielnie modyfikować obsługę błędów, co pozwala nam na pełną swobodę i wdrążanie nowych rozwiązań.

 

Testowanie


PayU daje nam duże pole do popisu w tej kwestii. Do dyspozycji mamy Sandbox i 2 serwery testowe. Zaczynając od komunikacji z serwerem mamy możliwość nasłuchu serwera, na który wysyłamy requesty, które zostają porównywane z dokumentacją i znacznie ułatwiają wykrycie błędu. W tym celu rekomendowane jest też użycie programu Postman, który pozwoli nam na ominięcie problemów w kodzie i przetestowanie samego zapytania, co daje nam możliwość na szybsze wykrycie błędu. Sandbox natomiast daje nam możliwość na bez skrępowania wykonywanie testów płatności.

 

Przykładowy obiekt konfiguracji usługi PayU zrealizowany w jPALIO™ Groove $*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
	}


}

 
Przykładowy obiekt README dla integracji usługi PayU $*api.payU.config.README

 

*** INTEGRACJA SKLEPU Z PAYU *** 

        *PRZEBIEG PŁATNOSCI*
        
1. Uzyskaj token dostępu w standardowym sposobie płatności (access_token w client_credentials),
2. Wyślij request o tworzenie zamówienia za pomocą odebranego tokena dostępu,
3. Przekierowanie klienta na otrzymany link.


        *UWAGI*
        
Wszystkie kwoty należy podawać w najmniejszej jednostce dla danej waluty np. w groszach
    dla PLN czyli "1000" oznacza 10 zł. Wyjątkiem jest HUF, który należy pomnożyć razy 100

Tworzenie zamowienia pola wymagane
    customerIp      IP kupującego
    merchantPosId   Identyfikator punktu płatności na którym zostanie wykonana płatność
    description     Opis zamówienia
    currencyCode    Symbol waluty używanej przez sklep w standardzie ISO 4217, np. "PLN"
    totalAmount     Całkowity koszt zamówienia w groszach 1000 = 10zl
    products        Sekcja zawiera dane o produktach. Sekcja <products> to tablica obiektów typu <product>.
 Mocno zalecane
     buyer          Sekcja przechowująca dane kupującego.Jej użycie jest mocno zalecane,
                    ponieważ w przypadku braku podania tej sekcji, użytkownik będzie proszony o uzupełnienie danych na stronie PayU, a płatność ratalna i odroczona nie będzie możliwa.
                   Opis pól sekcji <buyer>
Products pola wymagane
    name            Nazwa
    unitPrice       Cena jednostkowa
    quantity        Liczba sztuk
Inne
    notifyUrl       adres URL, na który przychodzić będą powiadomienia o zmianie statusu zamówienia lub zwrotu.
    continueUrl     Adres na jaki będzie przekierowany płatnik po zakończeniu procesu płatności. Jeśli płatność się nie powiodła, do adresu dodany zostanie parametr error=501...
    
        *WYJASNIENIA*
        
Uwierzytelnienie polega na pobraniu tokena OAuth'owego.
Token używany jest w dalszej komunikacji z serwerami PayU.
Dane potrzebne do autoryzacji znajdują się w panelu menadżerskim.
Rozróżniamy dwa tryby dostępów: client_credentials służący do standardowej integracji
oraz trusted_merchant służący do komunikacji tokenowej (PayU | Express).



        *IMPLEMENTACJA*

Utworz plik PayUDao, ktory umozliwi komunikacje miedzy stroną a bazą.
W celu sprawdzenia poprawności kodu mozna stworzyc strone z obiektem i zawartościa:
$//$*portal.model.beans.invokeStaticMethod("api.payU.PayUController","createTokeAndOrder",null )
a następnie włączyć strone w przeglądarce, efektem akceptacji powinno byc przekierowanie na strone PayU.

Przyklad poprawnej implementacji znajduje się na serwerze jerp.bibula.pl instacji bibula_b2b.

Większość zmian które muszą zostać dokonane znajdą się pliku Configuration (api.payU.config.Configuration).
Skrypty do tworzenie tablic w bazach danych znajdują się w pliku sqlScripts (api.payU.config.sqlScripts).
        
Ustawić swoje dane w api.payU.PayUController getAccessToken() np.
    Typ płatności (grant_type):                 client_credentials
    Protokół OAuth (client_id):         300746
    Protokół OAuth (client_secret):     2ee86a66e5d97e3fadc400c9f19b065d
    
Zmienić url na który zostaje wysłany POST na ten od PayU (w razie testów na serwer który mozemy nasłuchiwac lub sandbox)
w api.payU.PayUController httpPostPayU(), getAccessToken(), createOrder() np.
httpPostPayU("https://private-anon-81288937ba-payu21.apiary-mock.com/pl/standard/user/oauth/authorize", ..., ... )
            
    
        *LEGENDA*
        
Opis pól obiektu typu <product>
    Rekord         Opis                              Wymagany w obrębie sekcji
    name           Nazwa                                   Tak
    unitPrice      Cena jednostkowa                        Tak
    quantity       Liczba sztuk                            Tak
    virtual        Produkt może być wirtualny lub
materialny; przyjmuje
                   wartości true i false.             Nie
    listingDate    (marketplace) Data wystawienia
produktu, przykład:
                            "2016-01-26T17:35:37+01:00"    Nie        
    
Opis pól sekcji <buyer>
    Rekord                                        Opis                                                Wymagany w obrębie sekcji
    customerId                                Id kupującego                                Nie
    extCustomerId                            Identyfikator kupującego
                                                        używany w systemie klienta    Nie
    email                                            Adres email kupującego            Tak
    phone                                            Numer telefonu                            Nie
    firstName                                    Imię kupującego                            Nie
    lastName                                    Nazwisko kupującego                    Nie
    nin                                                PESEL lub zagraniczny
                                                        ekwiwalent                                    Nie
    language                                    Określa język strony płatniczej oraz język wiadomości e-mail wysyłanych
                                                        przez PayU do płatnika -
                                                        dostępne parametry są tutaj    Nie
    buyer.delivery                        Sekcja zawierająca dane adresowe
                                                        do wysyłki towaru                     Nie
                                                        
Opis pól w sekcji <buyerDelivery>
    Rekord                                        Opis                                        Wymagany w obrębie sekcji
    street                                        Ulica                                        Tak
    postalBox                                    Skrytka pocztowa                Nie
    postalCode                                Kod pocztowy                        Tak
    city                                            Miasto                                    Tak
    state                                            Województwo                            Nie
    countryCode                                Kod kraju                                Tak
    name                                            Nazwa adresu                        Nie
    recipientName                            Nazwisko adresata                Tak
    recipientEmail                        Adres email adresata        Nie
    recipientPhone                        Numer telefonu adresata    Nie        
        
Opis pól w sekcji <order>
    Rekord                                        Opis
    orderId                                        Identyfikator zamówienia nadany przez system PayU
    extOrderId                                Zewnętrzny identyfikator zamówienia (nadawany przez sklep)
    orderCreateDate                        Znacznik czasu dla utworzenia zamówienia
    notifyUrl                                    Adres pod który będą przesyłane powiadomienia
    customerIp                                IP kupującego
    merchantPosId                            Identyfikator punktu płatności na którym zostanie wykonana płatność
    validityTime                            Czas w trakcie którego możliwe jest dokończenie zamówienia w sekundach
    description                                Opis wykonywanego uznania
    additionalDescription            Dodatkowy opis zamówienia
    currencyCode                            Symbol waluty używanej przez sklep w standardzie ISO 4217, np. "PLN".
    totalAmount                                Całkowity koszt zamówienia
    status                                        Status zamówienia
    buyer                                            Sekcja przechowująca dane kupującego.

Opis pól w sekcji <status>
    Rekord                                        Opis
    statusCode                                Kod odpowiedzi
    statusDesc                                Opis statusu odpowiedzi

Dodatkowe
    Rekord                                        Opis
    "expires_in":43199                czas ważności w sekundach

    
    

        *ADRES HOSTA*
        
Produkcja:    https://secure.payu.com/
Sandbox:        https://secure.snd.payu.com/
Adres                                        Metoda HTTP  Komentarz     Pełne omówienie
/pl/standard/user/oauth/authorize               POST      Dostarcza token autoryzacyjny (OAuth).    Uwierzytelnienie komunikatów
api/v2_1/paymethods                             POST      Dostarcza aktualnie dostępne metody płatności.    Pobranie metod płatności
/api/v2_1/orders                                POST      Tworzy zamówienie i umożliwia przeprowadzenie płatności.    Tworzenie nowego zamówienia przez API
/api/v2_1/orders/{orderId}                      GET       Pozwala pobrać dane i status zamówienia.    Pobrania danych zamówienia
/api/v2_1/orders/{orderId}                      DELETE    Pozwala anulować zamówienie.    Anulowanie zamówienia
/api/v2_1/orders/{orderId}/transactions         GET       Pozwala pobrać szczegóły płatności (dane konta bankowego lub karty płatniczej).    Pobranie danych transakcji
/api/v2_1/orders/{orderId}/status               PUT       Pozwala odebrać (rozliczyć) opłacone zamówienie.    Odebranie zamówienia
/api/v2_1/orders/{orderId}/refunds              POST      Pozwala na pełne lub częściowe zwroty (uznania) do płatności.    Zwroty
/api/v2_1/payouts                               POST      Pozwala zlecić wypłatę bezpośrednio z aplikacji sklepu (wypłaty automatyczne i ad hoc są też dostępne poprzez Panel).    Wypłaty
api/v2_1/mcp-partners/{mcpPartnerId}/fx-table   GET       Pozwala pobrać tabelę kursową.    Płatności wielowalutowe
/api/v2_1/reports/{reportId}                    GET       Pozwala pobrać wygenerowane zestawienie transakcji (zestawienia automatyczne i ad hoc są też dostępne poprzez Panel).    Zestawienia transakcji
/api/visa-checkout/proxy/payment/data/{callId}  GET       Pozwala pobrać dane (maskowany numer karty, adres wysyłki itp.) z Visa Checkout.    Visa Checkout
        



        *PRZYDATNE LINKI*
        
REST API 2.1 dla the PayU system płatnosci.
    https://payu21.docs.apiary.io/#
    
Nasłuchiwanie serwera PayU.
    https://payu21.docs.apiary.io/traffic
    
Kody statusów od PayU.
    http://developers.payu.com/pl/restapi.html#references_statuses
    
Parametry komunikatów JSON.
    http://developers.payu.com/pl/restapi.html#references_api_parameters
    
Sandbox PayU.
    http://developers.payu.com/pl/overview.html#sandbox
    
Zestawienie endpointów.
    http://developers.payu.com/pl/overview.html#endpoint_reference

Support techniczny PayU.
    tech@payu.pl

   


Powrót