To rozwiązanie jest przestarzałe. Aby sprawdzić aktualne rozwiązania dotyczące stokenizowanych płatności kartami, w tym "Secure Form", przejdź do strony: Tokenizacja kart.
PayU|Express opiera się na transparentnej integracji, tj. odbywa się bez przekierowania na formularz PayU. Pomimo tego taka integracja jest bezpieczna i minimalizuje obowiązki wynikające z PCI DSS. Ponadto daje więcej elastyczności i zwiększa konwersję (ilość udanych płatności), ponieważ płatność odbywa się na stronie sklepu.
Proces płatności odbywa się w dwóch krokach - najpierw należy uzyskać dane karty (poprzez widget PayU lub poprzez formularz), a następnie obciążyć kartę. Dane karty są zwracane z PayU w postaci tokena wraz maskowanym numerem karty oraz datą ważności - sklep nie otrzymuje i nie musi przetwarzać pełnego numeru karty.
Tokeny zwrócone przez PayU mogą być jednorazowe lub wielorazowe. Tokeny wielorazowe mogą posłużyć do przyszłych płatności. Funkcjonalność ta skierowana jest do sklepów mających dużą ilość powracających klientów – połączenie konta użytkownika w sklepie z tokenem wielorazowym umożliwia dokonywania płatności bez każdorazowego podawania danych karty. Zwykle płatności zapisaną kartą mogą być wykonane ekspresowo, jednym kliknięciem przycisku "Płacę", jednak ze względów bezpieczeństwa niektóre transakcje mogą wymagać uwierzytelnienia przez przekierowanie na stronę banku-wydawcy karty (3D Secure) lub podanie kodu CVV2/CVC2. W związku z tym, płatności usługą PayU|Express powinny być inicjowane przez płatnika i z jego udziałem, a nie wyłącznie przez sklep, tak jak w przypadku płatności cyklicznych.
PayU|Express wymaga specjalnej konfiguracji po stronie PayU. Dlatego przed przystąpieniem do integracji należy skontaktować się z opiekunem handlowym w PayU.
Na środowisku Sandbox punkty płatności typu REST API zostaną skonfigurowane automatycznie pod możliwość testowania tej funkcjonalności w ciągu 90 minut od utworzenia.
Zanim przystąpisz do integracji usługi, zapoznaj się z zaleceniami i wymogami przygotowanymi przez ekspertów ds. bezpieczeństwa w PayU. Ich przestrzeganie pomoże zminimalizować ryzyko związane z transakcjami oszukańczymi.
Płatność z tokenem jednorazowym (pierwsza): 
Płatność z tokenem wielorazowym (druga i kolejne): 
Uwaga: w przypadku widgeta w wersji inline oraz pól "input", należy wyświetlić treści opisane w sekcji Obowiązki informacyjne.
Ten rodzaj widgeta może przekazać dane za pomocą metody POST albo funkcji callback.
value:"TOK_1IOPVS7EMKVT4GYvs44XPxAOb8yc",
maskedCard:"424242******4242",
tokenType:"STANDARD",
type:"CARD_TOKEN"
| Nazwa parametru | Opis |
|---|---|
| value | token jednorazowy ("TOK_") - wygasa po pierwszym użyciu |
| maskedCard | maskowany numer karty |
| tokenType | stała wartość (zawsze STANDARD) |
| type | stała wartość (zawsze CARD_TOKEN) |
<form action="http://exampledomain.com/processOrder.php" method="post">
<button id="pay-button">Pay now</button>
</form>
Uwaga: widget może przekazać dane poprzez metodęDla porównania przykład dot. widgetu inline:HTTP POSTlub poprzez funkcję callback. Aby jej użyć, należy w skrypcie podać parametrsuccess-callback.
<script
src="https://secure.payu.com/front/widget/js/payu-bootstrap.js"
pay-button="#pay-button"
merchant-pos-id="145227"
shop-name="Nazwa sklepu"
total-amount="9.99"
currency-code="PLN"
customer-language="pl"
store-card="true"
customer-email="email@exampledomain.com"
sig="250f5f53e465777b6fefb04f171a21b598ccceb2899fc9f229604ad529c69532">
</script>
<script
src="https://secure.payu.com/front/widget/js/payu-bootstrap.js"
merchant-pos-id="145227"
shop-name="Shop name"
total-amount="9.99"
currency-code="PLN"
customer-language="pl"
widget-type="cvv"
cvv-url="https://secure.payu.com/api/v2/token/token.json?refReqId=c4b31c492b0a5aaa9eb12d07578286a0"
cvv-success-callback="cvvSuccess"
sig="e08f617240bac43954bcbb5782a0ce203a23717ba9760be71c9ea8cab127ad12">
</script>
<script type="text/javascript">
function cvvSuccess() {
//wyświetla stronę o udanym zainicjowaniu płatności
}
</script>
Widget inline to modyfikacja widgeta pop-up. Nie zawiera on nagłówka z nazwą sklepu i kwoty zakupu oraz wykorzystuje dodatkowe parametry.
<div id="payu-widget"></div>
HTTP POSTlub poprzez funkcję callback. Aby jej użyć, należy w skrypcie podać parametr success-callback.
Funkcja callback może wyglądać jak poniżej (poniższy przykład pozwala wyświetlić dane
w konsoli w przeglądarce):
<script>
function test($data) {
console.log("callback");
console.log($data);
}
</script>
<script
src="https://secure.payu.com/front/widget/js/payu-bootstrap.js"
merchant-pos-id="145227"
shop-name="TEST"
total-amount="12345"
currency-code="PLN"
customer-language="en"
store-card="true"
payu-brand="false"
success-callback="test"
widget-mode="use"
customer-email="test@test.com"
sig="203ec8c4b9571ce6b4c03058f57264f04d06d00a86da19390d47ba1be4551578">
</script>
Parametr SIG (służący zabezpieczeniu widgeta przed modyfikacją) należy wyliczyć w następujący sposób:
Parametry widgeta, które mają zostać użyte należy posortować wg nazwy (klucza) parametru:
Następnie należy połączyć wartości parametrów i uzyskać ciąg znaków jak poniżej:
PLNtest@test.compl145227TEST12345
i dodać do niego wartość klucza drugiego (w przykładzie użyty został testowy POS produkcyjny). Uzyskany ciąg znaków, na którym na którym należy użyć funkcji skrótu SHA256 to:
PLNtest@test.compl145227TEST1234513a980d4f851f3d9a1cfc792fb1f5e50
A uzyskana wartość sig, po zastosowaniu funkcji skrótu, to:
cf16a6302c26e6f39b580be859caf1fe396e81366c4d8f56fb765fb374e8ed3a
| Nazwa parametru | Wymagany | Wymagany dla SIG | Opis |
|---|---|---|---|
| pay-button | tak | nie | Selektor CSS dla przycisku płatności. |
| merchant-pos-id | tak | tak | Identyfikator POSa użytego do płatności. |
| shop-name | tak | tak | Nazwa sklepu, która pojawi się na widgecie. |
| total-amount | tak | tak | Kwota płatności, która pojawi się na widgecie. |
| currency-code | tak | tak | Waluta płatności. Musi być zgodna z walutą POSa. |
| customer-language | tak | tak | Język w którym zostanie wyświetlony widget. Dostępne wartości to: pl, bg, cs, de, en, es, fr, hu, it, pt, ro, sk. |
| customer-email | nie | tak | Email posiadacza karty. |
| widget-type | nie | nie | Domyślnie widget pokazuje formularz do podania pełnych danych karty. Podanie wartości 'cvv' wywoła widget służący tylko do podania danych karty. Widget 'cvv' wymaga zestawu nieco innych parametrów (zob. tabela poniżej). |
| store-card | nie | tak | Wartości 'true'/'false'. Wartość 'true' oznacza wyświetlenie widgeta z opcją 'Zapisz kartę'. |
| recurring-payment | nie | tak | Wartości 'true'/'false'. Podanie wartości 'true' wyświetla widget w wersji dla płatności cyklicznych (wówczas należy zadeklarować 'true' również dla parametru store-card. |
| payu-brand | nie | tak | Wartości: true/false (domyślnie: "true"). Wyświetla widget bez znaku PayU (tylko dla widgeta w wersji inline). |
| widget-mode | nie | tak | Wartości: pay/use (domyślnie: "pay"). Konfiguruje przyciski na widgecie. Opcja "Pay" zakłada, że płatność następuje zaraz po użyciu widgeta. Opcja "use" pozwala pobrać dane karty, bez ich natychmiastowego użycia. |
| success-callback | nie | nie | Nazwa funkcji, która przechwytuje dane przekazane przez widget. |
| sig | tak | nie | Wartość SIG wyliczona zgodnie z opisem powyżej. |
| Nazwa parametru | Wymagany | Wymagany dla SIG | Opis |
|---|---|---|---|
| merchant-pos-id | tak | tak | Identyfikator POSa użytego do płatności. |
| shop-name | tak | tak | Nazwa sklepu, która pojawi się na widgecie. |
| total-amount | tak | tak | Kwota płatności, która pojawi się na widgecie. |
| currency-code | tak | tak | Waluta płatności. Musi być zgodna z walutą POSa. |
| customer-language | tak | tak | Język w którym zostanie wyświetlony widget. Dostępne wartości to: pl, en, cs oraz de, es, fr, it, pt. |
| widget-type | tak | nie | Należy użyć wartości 'cvv' |
| cvv-url | tak | tak | Musi mieć wartość równą albo 'redirectUri' (zwróconą przez PayU w komunikacie OrderCreateResponse z kodem WARNING_CONTINUE_CVV) albo, w przypadku wywołania widgetu po udanym powrocie ze strony banku-wydawcy karty w procesie 3DS, wartość 'refReqId' dodaną jako query string do parametru 'continueUrl' podanego w OrderCreateRequest. |
| cvv-success-callback | nie | nie | Funkcja callback wywoływana po tym jak płatnik podał kod CVV2/CVC2 i została dokonana autoryzacja karty. |
| sig | tak | nie | Wartość SIG wyliczona zgodnie z opisem powyżej. |
W przypadku włączenia płatności kartowych jesteś zobowiązany do przestrzegania norm PCI DSS.
Powinieneś co roku wypełnić Self-Assessment Questionnaire (SAQ), a także wykonywać kwartalny skan sieci przeprowadzany przez jednostkę weryfikującą - Approved Scan Vendor (ASV).
Dodatkowo, jeżeli przetwarzasz ponad 6 milionów transakcji rocznie powinieneś wykonać Report on Compliance (ROC), przeprowadzany przez certyfikowanego audytora - Qualified Security Assessor (QSA).
Więcej informacji możesz znaleźć na stronieSecurity Standards Council.
<script src="https://secure.payu.com/res/v2/openpayu-2.1.js"></script>
<script src="https://secure.payu.com/res/v2/plugin-token-2.1.js"></script>
Utwórz formularz pobrania danych karty w sposób, który umożliwi poprawne działanie skryptu. W tym celu umieść elementy typu "input" na swojej stronie, których atrybuty "class" są nazwane tak jak w przykładzie poniżej.
Uwaga: nie jest konieczne umieszczenie elementów "input" w elemencie "form" ponieważ dane karty nie powinny zostać wysłane na Twój serwer.
W przypadku kiedy chcesz wysłać dane karty i spełniać wszystkie wymogi określone przez PCI DSS, zob. rozdz. Dane kartowe w postaci tekstowej.
<table>
<tr>
<td>Numer karty</td>
<td><input type="text" class="payu-card-number"></td>
</tr>
<tr>
<td>CVV2/CVC2</td>
<td><input type="text" class="payu-card-cvv"></td>
</tr>
<tr>
<td>miesiąc</td>
<td><input type="text" class="payu-card-expm"></td>
</tr>
<tr>
<td>rok</td>
<td><input type="text" class="payu-card-expy"></td>
</tr>
<tr>
<td>Akceptacja regulaminu Konta PayU i zgoda na zapisanie karty</td>
<td><input type="checkbox" value="false" class="payu-agreement"></td>
</tr>
<input type="hidden" class="payu-customer-email" value="...@...">
<tr>
<td><input type="submit" id="payu-cc-form-submit"></td>
</tr>
</table>
Skrypty wyszukują następujące nazwy klas:
| Nazwa | Wymagana | Opis |
|---|---|---|
| payu-card-cardholder | opcjonalna | Imię i nazwisko posiadacza karty. |
| payu-card-number | tak | Numer karty płatniczej. |
| payu-card-cvv | tak | Kod bezpieczeństwa karty (CVV2/CVC2). |
| payu-card-expm | tak | Miesiąc daty ważności. |
| payu-card-expy | tak | Rok daty ważności. |
| payu-agreement | tak | Wartości true/false. Oznacza zgodę posiadacza karty na zapisanie danych i regulamin Konta PayU. Przy wartości false PayU nie zwróci tokena wielorazowego. |
| payu-customer-email | opcjonalna | Adres email posiadacza karty. |
(function () {
var button = document.querySelector('#payu-cc-form-submit');
button.addEventListener('click', function (event) {
OpenPayU.merchantId = 'your POS ID';
var result = OpenPayU.Token.create({}, function (data) {
// obsłuż rezultat tokenizacji, możliwe kody odpowiedzi są poniżej
});
if (result !== true) {
// żądanie tokenizacji nie zostało wysłane,
// sprawdź błędy walidacji w obiekcie "result"
}
}, false);
})();
true, a
poniższe obiekty są przekazane do funkcji callback. Wartość zmiennej
token należy przekazać do backendu i dołączyć do
OrderCreateRequest (zob. rozdz. Płatność tokenem).
{
data: {
mask: "444433******1111",
token: "TOK_1JKQSX1FMNTU831B8a6z4LDHbzsv",
type: "STANDARD"
},
status: {
statusCode: "SUCCESS",
codeLiteral: "SUCCESS",
code: "0"
}
}
{
card.expirationDate: "formatInvalid",
card.expirationMonth: "formatInvalid",
card.expirationYear: "formatInvalid",
card.number: "unsupportedType"
}
Kody odpowiedzi na żądanie tokenizacji:
| Code | Status code | Code literal | Opis |
|---|---|---|---|
| 0 | SUCCESS | SUCCESS | Udana tokenizacja, odp. zawiera obiekt "data". |
| 100 | ERROR_INTERNAL | GENERAL_ERROR | Inny bład. |
| 101 | ERROR_UNKNOWN_MERCHANT_POS | UNKNOWN_MERCHANT | Nieprawidłowa wartość POS ID. |
| 4003 | ERROR_VALUE_INVALID | CARD_INVALID_CVV | Długość CVV2 jest nieprawidłowa (może zawierać tylko 3 lub 4 znaki). |
| 4100 | SERVICE_NOT_AVAILABLE | CARD_TOKENIZATION_DISABLED | Usługa tokenizacji nie została włączona dla danego POS ID. |
| 4101 | SERVICE_NOT_AVAILABLE | CARD_MERCHANT_INACTIVE | Płatność kartą nie została włączona dla danego POS ID. |
Device fingerprint to informacja zebrana o urządzeniu w celu jego identyfikacji.
Wartość "device fingerprint" jest tworzona przez statyczną funkcję Fingerprint2.get, która zastąpiła skrypt new Fingerprint2().get, przez to wynik nie będzie już automatycznie hash'owany.
Potrzebne biblioteki można znaleźć Tutaj.
var options = {}
Fingerprint2.get(options, function (components) {
// components is array of {key: 'foo', value: 'component value'}
...
})
// or
Fingerprint2.getPromise(options).then(function (components) {
// components is array of {key: 'foo', value: 'component value'}
...
})
Fingerprint2.get(options, function (components) {
var values = components.map(function (component) { return component.value })
var murmur = Fingerprint2.x64hash128(values.join(''), 31)
})
Uzyskaną wartość należy przesłać do PayU poprzez backend (zob. niżej).
Twoja strona powinna również obsłużyć pobranie brakującego kodu CVV2.
<input type="text" class="payu-card-cvv">
Potrzeba pobrania wyłącznie kodu CVV2 może wystąpić w przypadku konieczności uwierzytelnienia płatności tokenem kartowym.
Wystąpić mogą 2 przypadki:
continueUrl w OrderCreateRequest. Przykład
zapytania:
https://your.shop.com/payment?statusCode=WARNING_CONTINUE_CVV&refReqId=b20399775cbf48a00469280499bdd912
Przykład skryptu (kod poniżej powinien zostać wywołany kiedy płatnik użyje
przycisku do wysłania CVV2):
var url = "refReqId=" + 'wartość refReqId podana w zapytaniu (query string)';
var options = {url: url};
OpenPayU.authorizeCVV(options, function(data) {
if (data.status === 'SUCCESS') {
// CVV2 przesłany poprawnie, można ukryć pole input
} else {
// wystąpił błąd (zob. tabelę powyżej)
}
});
var options = {url: 'wartość redirectUri z OrderCreateResponse'};
OpenPayU.authorizeCVV(options, function(data) {
if (data.status === 'SUCCESS') {
// CVV2 przesłany poprawnie, można ukryć pole input
} else {
// wystąpił błąd (zob. tabelę powyżej)
}
});
Token wielorazowy (TOKC_) tworzony jest po pierwszym użyciu tokenu jednorazowego (TOK_).
Komunikat OrderCreateRequest należy rozszerzyć o sekcję Buyer
oraz sekcję payMethods podając jako wartość token jednorazowy
(TOK_). Tworzenie zamówienia (Order) poprzez REST API jest opisane w rozdziale
Tworzenie zamówienia.
cardOnFile, który informuje o stronie inicjującej
płatność:
Szczegółowy opis wartości parametru cardOnFile możesz znaleźć
w sekcji Parametry JSON.
Odpowiednie ustawienie tego
parametru pozwoli na zwiększenie konwersji dla kart płatniczych.
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":"Laptop",
"currencyCode":"PLN",
"totalAmount":"15000",
"extOrderId":"[generateExtOrderId]",
"products":[
{
"name": "Laptop",
"unitPrice":"15000",
"quantity": "1"
}
],
"buyer": {
"email": "john.doe@example.com",
"firstName": "John",
"lastName": "Doe",
"language": "pl"
},
"payMethods": {
"payMethod": {
"value": "TOK_1IHRPT6HKSSS3H62K0GS8pElP862",
"type": "CARD_TOKEN"
}
},
"deviceFingerprint": "[generateFingerPrint2]"
}'
Uwierzytelnienie komunikatu jest opisane w rozdziale Uwierzytelnienie.
Uwaga! POS użyty w przykładzie nie ma włączonej usługi tokenizacji.
{
"orderId": "ORDER_ID",
"payMethods": {
"payMethod": {
"card": {
"number": "424242******4242",
"expirationMonth": "12",
"expirationYear": "2017"
},
"type": "CARD_TOKEN",
"value": "TOKC_KPNZVSLJUNR4DHF5NPVKDPJGMX7"
}
},
"status": {
"statusCode": "SUCCESS",
"statusDesc": "Request successful"
}
}
Oznacza to, że zamówienie zostało przyjęte bez potrzeby dodatkowego uwierzytelnienia płacącego (3D Secure lub podanie kodu CVV2) i możesz oczekiwać na status zamówienia na adres podany w parametrze notifyUrl w komunikacie OrderCreateRequest.
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":"Laptop",
"currencyCode":"PLN",
"totalAmount":"15000",
"cardOnFile": "STANDARD_MERCHANT",
"extOrderId":"9xl0x8nr1wk7m0i3ltqbja",
"products":[
{
"name": "Laptop",
"unitPrice":"15000",
"quantity": "1"
}
],
"buyer": {
"email": "john.doe@example.com",
"firstName": "John",
"lastName": "Doe",
"language": "en"
},
"payMethods": {
"payMethod": {
"value": "TOKC_2IHRST6HKSST3H62K2GS8pElI862",
"type": "CARD_TOKEN"
}
},
"deviceFingerprint": "0372098a4a90927db053463454491d78"
}'
W przypadku odpowiedzi z kodem WARNING_CONTINUE_3DS, należy przekierować płatnika
na
stronę (parametr redirectUri) banku, wydawcy karty w celu
dodatkowego uwierzytelnienia płatności w procesie 3D Secure.
{
"status": {
"statusCode": "WARNING_CONTINUE_3DS",
"severity": "WARNING"
},
"redirectUri": "{redirectUri}",
"threeDsProtocolVersion": "3DS2",
"orderId": "ORDER_ID"
}
{
"status": {
"statusCode": "WARNING_CONTINUE_3DS",
"severity": "WARNING"
},
"redirectUri": "{redirectUri}",
"threeDsProtocolVersion": "3DS2",
"orderId": "ORDER_ID",
"payMethods": {
"payMethod": {
"card": {
"number": "401200******1112",
"expirationMonth": 12,
"expirationYear": 2020
},
"type": "CARD_TOKEN",
"value": "TOKC_H1ZOE5YXLJPKMUUSDSJRARON0WH"
}
}
}
continueUrl w
OrderCreateRequest. Przy czym do adresu w zapytaniu (query string)
dodawane są dwa parametry:
statusCode - wartość SUCCESS lub WARNING_CONTINUE_CVV;refReqId - losowy alfanumeryczny ciąg znaków.https://your.shop.com/payment?statusCode=SUCCESS&refReqId=5c867936fbb3cc2c373820b4550b4645
W przypadku gdy parametr statusCode przyjął wartość SUCCESS, to oznacza, że
zamówienie zostało przyjęte bez potrzeby kolejnego uwierzytelnienia płacącego i
możesz oczekiwać na status zamówienia.
Natomiast gdy parametr statusCode przyjął wartość WARNING_CONTINUE_CVV, to
wówczas powinieneś wyciągnąć wartość parametru refReqId wraz z nazwą
parametru, przykładowo:
refReqId=5c867936fbb3cc2c373820b4550b4645
redirectUri i
przekaż tę wartość, w zależności od sposobu integracji:
{
"orderId": "ORDER_ID",
"status": {
"statusCode": "WARNING_CONTINUE_CVV",
"severity": "WARNING"
},
"redirectUri": "{redirectUri}"
}
Przykładowa wartość parametru redirectUri:
https://secure.payu.com/api/v2/token/token.json?refReqId=11ed628ebe88ef6837d90ebb26f1a8b9
Po podaniu przez płacącego kodu CVV2/CVC2 możesz oczekiwać na status zamówienia.
Zalecamy, aby metody płatności dostępne dla danego użytkownika nie były przechowywane lokalnie przez sklep, ale raczej pobierane od PayU. Pobierane są zarówno zapisane metody płatności (tokeny) oraz standardowe metody płatności. Użycie tej usługi daje następujące korzyści:
- zwracane są wyłącznie metody płatności dostępne w danym momencie dla danego użytkownika,
- zwrócone tokeny są zawsze aktualne i zsynchronizowane z aktywnym Kontem PayU danego użytkownika.
W celu pobrania metod płatności należy najpierw uzyskać token dostępowy OAuth2.
Aby uzyskać token dostępowy należy wywołać żądanie metodą POST na endpoint
/pl/standard/user/oauth/authorize.
Żądanie należy wywołać z grant_type równym trusted_merchant.
Przykładowe żądanie:
curl -X POST https://secure.payu.com/pl/standard/user/oauth/authorize \
-H "Cache-Control: no-cache"
-H "Content-Type: application/x-www-form-urlencoded"
-d 'grant_type=trusted_merchant&client_id=[provided by PayU]&client_secret=[provided by PayU]&email=[users email]&ext_customer_id=[Id of the customer used in merchant system]'
ext_customer_id jest identyfikatorem klienta w systemie merchanta, jest on konieczny w celu poprawnego
wygenerowania tokena OAuth.
{
"access_token": "4099c2c3-276f-488a-90e2-32620ac441dc",
"token_type": "bearer",
"expires_in": 43199,
"grant_type": "trusted_merchant"
}
Należy wstawić uzyskany token dostępowy do nagłówka i wywołać żądanie metodą GET na
endpoint api/v2_1/paymethods .
curl -X GET https://secure.payu.com/api/v2_1/paymethods \
-H "Authorization: Bearer 87ad751f-7ea5-4023-a16f-04b6647a07f5"
-H "Cache-Control: no-cache"
Przykładowa odpowiedź (HTTP 200). Opis poszczególnych pól jest poniżej.
{
"cardTokens":[
{
"cardExpirationYear":"2017",
"cardExpirationMonth":"12",
"cardNumberMasked":"411111******1111",
"cardBrand":"VISA",
"value":"TOKC_XATB7DF8ACXYTVQIPLWTVPFRKQE",
"brandImageUrl":"http://static.payu.com/images/mobile/visa.png",
"preferred":true,
"status":"ACTIVE"
},
{
"cardExpirationYear":"2014",
"cardExpirationMonth":"12",
"cardNumberMasked":"424242******4242",
"cardBrand":"VISA",
"value":"TOKC_XATB7DF8ACXYTVQIPLWTVPFRKQE",
"brandImageUrl":"http://static.avocado.qxlint/images/mobile/visa.png",
"preferred":false,
"status":"EXPIRED"
}
],
"pexTokens":[
{
"accountNumber":"5311...7744",
"payType":"mtex",
"value":"TOKE_XPJ4UKJGHVRPMQPGB6X1JJQCUSS",
"name":"account name set by the user",
"brandImageUrl":"http://static.payu.com/images/mobile/logos/pex_mbank.png",
"preferred":false,
"status":"ACTIVE"
}
],
"payByLinks":[
{
"value":"c",
"name":"Płatność online kartą płatniczą",
"brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_c.png",
"status":"ENABLED",
"minAmount": 50,
"maxAmount": 100000
},
{
"value":"o",
"name":"Pekao24Przelew",
"brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_o.png",
"status":"DISABLED",
"minAmount": 50,
"maxAmount": 100000
},
{
"value":"ab",
"name":"Płacę z Alior Bankiem",
"brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_ab.png",
"status":"TEMPORARY_DISABLED",
"minAmount": 50,
"maxAmount": 100000
}
]
}
| Parametr | Opis |
|---|---|
| cardExpirationYear | Rok ważności karty w formacie RRRR |
| cardExpirationMonth | Miesiąc ważności karty w formacie MM |
| cardNumberMasked | Maskowany numer karty (pierwsze 6 i ostatnie 4 cyfry). |
| cardBrand | Rodzaj karty. Wartości: 'VISA', 'MASTERCARD', 'MAESTRO'. Inne rodzaje nie są wspierane. VISA oznacza różne marki kart Visa, w tym Visa Electron. MASTERCARD oznacza również MasterCard Debit. |
| value | Wartość tokena. |
| brandImageUrl | Odnośnik do grafiki na serwerze PayU reprezentującej logo karty. |
| preferred | Wartości true/false; 'true' oznacza ostatnio użyty token. |
| status | Wartości: 'ACTIVE' i 'EXPIRED'.
'EXPIRED' oznacza tokeny wygasłe, można ich nie prezentować lub prezentować wraz z prośbą o podanie aktywnego numeru karty (tj. ponowne podanie numeru karty wygasłej wraz z nową datą ważności i CVV2/CVC2 lub zupełnie nowego numeru). Token nie będzie prezentowany, jeśli został anulowany przez użytkownika lub zablokowany ze względów bezpieczeństwa przez PayU. |
Tokeny PEX oznaczają rachunki bankowe dostępne przez usługę PayU|Express.
| Parametr | Opis |
|---|---|
| accountNumber | Pierwsze i ostatnie 4 cyfry rachunku bankowego. |
| payType | Represents payType of the token. Oznacza typ platności (bank) powiązany z danym tokenem. |
| name | Nazwa konta nadana przez użytkownika. |
| value | Wartość tokena. |
| brandImageUrl | Odnośnik do grafiki na serwerze PayU reprezentującej bank. |
| preferred | Wartości true/false; 'true' oznacza ostatnio użyty token. |
| status | Wartości: 'ACTIVE'.
Token nie będzie prezentowany, jeśli został anulowany przez użytkownika lub zablokowany ze względów bezpieczeństwa przez PayU. |
| Parametr | Opis |
|---|---|
| value | Wartość metody płatności. Dostępne wartości są tutaj. |
| name | Nazwa typu płatności nadana przez PayU. |
| brandImageUrl | Odnośnik do grafiki na serwerze PayU reprezentującej metodę płatności. |
| status | Możliwe wartości: 'ENABLED' (aktywna), 'DISABLED' (nieaktywna), 'TEMPORARY_DISABLED' (czasowo nieaktywna z uwagi na brak rozliczeń online po stronie banku - wartość wystąpi po dokonaniu dodatkowej konfiguracji przez PayU). |
W przypadku kiedy użytkownik zamyka swoje konto w sklepie internetowym lub chce usunąć zapisaną kartę, token należy skasować.
W tym celu należy wysłać żądanie z metodą DELETE na endpoint https://secure.payu.com/api/v2_1/tokens/{tokenValue}
Nagłówek powinien zawierać token dostępowy OAuth typu trusted.merchant.
Przykład:
curl -X DELETE https://secure.payu.com/api/v2_1/tokens/TOKC_XATB7DF8ACXYTVQIPLWTVPFRKQE \
-H "Authorization: Bearer cccbbc40-8113-443b-b4ea-c4b266272b22"
-H "Cache-Control: no-cache"
Uwaga! Ten sposób integracji jest przeznaczony tylko dla punktów płatności, które spełniają wymogi określone przez PCI DSS i są uprawnione do przetwarzania danych kartowych po swojej stronie. Wymagają również dodatkowej konfiguracji.. Dlatego przed przystąpieniem do integracji należy skontaktować się z opiekunem handlowym w PayU.
Do standardowego zamówienia OrderCreateRequest należy dodać
sekcję payMethods.payMethod zawierającą dane kartowe i
parametr cardOnFile z jedną z poniższych wartości:
Szczegółowy opis wartości parametru cardOnFile możesz
znaleźć w sekcji Parametry JSON.
Odpowiednie ustawienie tego parametru pozwoli zwiększyć konwersję dla kart płatniczych i zagwarantować odpowiednie bezpieczeństwo transakcji.
Jeżeli jest to płatność jednorazowa kartą, wówczas parametr
cardOnFile należy pominąć.
"payMethods": {
"payMethod": {
"card": {
"number":"5100052384536818",
"expirationMonth":"11",
"expirationYear":"2020",
"cvv":"123"
}
}
},
"payMethods": {
"payMethod": {
"card": {
"number":"5100052384536818",
"expirationMonth":"11",
"expirationYear":"2020",
"cvv":"123",
"firstTransactionId": "MCC0111LL1121"
}
}
},
Również dla płatności z podaniem danych kartowych w postaci tekstowej należy być przygotowanym na obsługę odpowiedzi z kodem WARNING_CONTINUE_3DS lub WARNING_CONTINUE_CVV.
W przypadku gdy jesteś zintegrowany z własnym dostawcą usługi 3D Secure
(zwany dalej w skrócie 3DS) masz możliwość przekazania parametrów będących wynikiem
procesu obsługi 3DS w komunikacie OrderCreateRequest. Standardowy komunikat
OrderCreateRequest należy rozszerzyć o sekcję
payMethods.threeDsData zawierającą dane wynikowe procesu 3DS.
Jeżeli wynik obsługi 3DS zostanie dostarczony wraz z zamówieniem, to kod odpowiedzi WARNING_CONTINUE_3DS nigdy nie zostanie zwrócony.
"payMethods": {
"payMethod": {
...
},
"threeDsData": {
"status3Ds": "Y",
"status3DsDescription": "Authentication successful",
"dsTransactionId": "3b31b19d-1c06-4ea4-a85a-00af10c66588",
"eciCode": 5,
"cavv": "AAABBBEAUAAAABgICABQAAAAAAA="
}
}
}
"payMethods": {
"payMethod": {
...
},
"threeDsData": {
"status3Ds": "A",
"status3DsDescription": "3DS authentication attempt",
"dsTransactionId": "3b31b19d-1c06-4ea4-a85a-00af10c66588",
"eciCode": 6,
"cavv": "BwABCJQnYgAAACdENCdiAAAAAAA="
}
}
}
| Parametr | Opis |
|---|---|
| status3Ds | Status 3DS. Dozwolona dziedzina wartości:
|
| status3DsDescription |
Opis związany z wynikiem 3DS.
Pole opcjonalne. Zachęcamy jednak do przekazywania, jeżeli używany MPI przekazuje również dodatkowy opis – pozwoli to usprawnić potencjalną obsługę klienta przez BOK. |
| xid |
XID, czyli unikalny identyfikator transakcji 3DS nadawany przez sklep.
Pole wymagane w ramach sekcji dla 3DS w wersji 1. Pole nie powinno być wysyłane dla 3DS2.x. |
| dsTransactionId | Pole wymagane w ramach sekcji dla 3DS2.x. Pole nie powinno być wysyłane dla 3DS w wersji 1. |
| eciCode |
E-commerce Indicator / UCAF.
Dozwolone wartości:
|
| cavv |
Kryptogram 3DS.
Pole opcjonalne. Powinno być zawsze przekazywane, jeżeli MPI przekazał tę informację. |
Poniżej znajduje się omówienie scenariuszy płatności, które należy zaimplementować.
redirectUri.continueUrl.notifyUrl.notifyUrl.redirectUri.continueUrl.notifyUrl.notifyUrl.