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 w sklepie internetowym za pośrednictwem usługi PayU składa się z dwóch etapów.
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ń.
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.
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
}
}
*** 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