Cykl życia płatności
Każda płatność w systemie PayU ma swój cykl życia, który składa się z etapów związanych z kluczowymi zdarzeniami, takimi jak akceptacja, rozliczenie i anulowanie.
Wprowadzenie
Możesz skonfigurować auto-odbiór oddzielnie dla każdej metody płatności za pośrednictwem panelu menedżerskiego.
Domyślnie automatyczne odbieranie jest włączone, a podstawowa procedura płatności wygląda następująco:
- Każda pomyślnie autoryzowana płatność dla zamówienia jest rejestrowana.
- Kupujący jest obciążany kwotą zamówienia.
- Saldo sklepu jest zwiększane o kwotę zamówienia.
- PayU nalicza prowizję do zamówienia.
Jeśli automatyczne odbieranie jest wyłączone, należy odebrać każde zamówienie przy użyciu metody PUT lub anulować przy użyciu metody DELETE.
Jeśli takie działanie nie zostanie podjęte, zamówienie zostanie automatycznie anulowane. Automatyczne anulowanie następuje po czasie wskazanym dla metody płatności.
Status | Opis |
---|---|
PENDING | Płatność jest obecnie przetwarzana. |
WAITING_FOR_CONFIRMATION | PayU oczekuje obecnie na odebranie płatności przez system akceptanta. Ten status pojawia się, jeżeli wyłączyłeś automatyczne odbieranie.. |
COMPLETED | Płatność została zaakceptowana. PayU wkrótce wypłaci środki. |
CANCELED | Płatność została anulowana, a kupujący nie został obciążony (z jego konta nie pobrano żadnych środków). |
Powiadomienia są wysyłane natychmiast po zmianie statusu płatności. Jeśli powiadomienie nie zostanie przez Ciebie odebrane, nastąpi ponowne wysłanie powiadomienia zgodnie z poniższą tabelą.
Próba | Czas ponownego wysłania |
---|---|
1 | natychmiast |
2 | 1 minuta |
3 | 2 minuty |
4 | 5 minut |
5 | 10 minut |
6 | 30 minut |
7 | 1 godzina |
8 | 2 godziny |
9 | 3 godziny |
10 | 6 godzin |
11 | 9 godzin |
12 | 12 godzin |
13 | 15 godzin |
14 | 18 godzin |
15 | 21 godzin |
16 | 24 godziny |
17 | 36 godzin |
18 | 48 godzin |
19 | 60 godzin |
20 | 72 godziny |
Powiadomienia
Aby włączyć powiadomienia dla konkretnej płatności, określ parametr notifyUrl
w żądaniu płatności. Każda płatność może otrzymać inny adres URL, na który będą wysyłane powiadomienia.
Każde powiadomienie jest wysyłane asynchronicznie. Po otrzymaniu przez system powiadomienia ze statusem COMPLETED, powinieneś ignorować wszelkie dalsze powiadomienia.
Po wysłaniu powiadomienia system PayU wymaga odpowiedzi z kodem HTTP statusu 200. Jeśli otrzyma inny kod statusu, wyśle powiadomienie ponownie. System powinien również uwzględniać sytuacje, w których powiadomienie jest wysyłane kilkukrotnie z tym samym statusem. Dla każdego powtórzonego powiadomienia również powinna zostać wysłana odpowiedź z kodem 200.
Aby zapewnić zaufaną komunikację między PayU a twoim sklepem, musisz zweryfikować wartość podpisu dostępną w nagłówku OpenPayu-Signature
za każdym razem, gdy Twój system otrzyma jakiekolwiek powiadomienie z serwera PayU. Więcej informacji możesz znaleźć w sekcji Weryfikacja podpisu powiadomień.
Powiadomienia są wysyłane dla zamówień o następujących statusach: PENDING, WAITING_FOR_CONFIRMATION, COMPLETED, CANCELED.
Powiadomienia są wysyłane w formacie JSON przy użyciu metody POST.
Aby uzyskać więcej informacji na temat parametrów, przejdź do Referencji API.
Jeśli filtrujesz adresy IP, pamiętaj, aby nie blokować IP używanych przez PayU do wysyłania powiadomień:
Produkcyjne
185.68.12.10, 185.68.12.11, 185.68.12.12, 185.68.12.26, 185.68.12.27, 185.68.12.28
Testowe (sandbox)
185.68.14.10, 185.68.14.11, 185.68.14.12, 185.68.14.26, `185.68.14.27, 185.68.14.28
Przykład powiadomienia
Poniżej znajdują się przykładowe powiadomienia jakie możesz otrzymać od PayU.
PayU-Processing-Time: 1000 // dla wybranych statusów
Content-Type: application/json;charset=UTF-8
User-Agent: Jakarta Commons-HttpClient/3.1
Content-Length: 100
Authorization: Basic MTIzNDU2Nzg6QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVo=
OpenPayu-Signature: sender=checkout;signature=d47d8a771d558c29285887febddd9327;algorithm=MD5;content=DOCUMENT
X-OpenPayU-Signature: sender=checkout;signature=d47d8a771d558c29285887febddd9327;algorithm=MD5;content=DOCUMENT
PayU-Processing-Time
pokazuje ile czasu trwało przetwarzanie po stronie PayU, do momentu próby wysłania pierwszej notyfikacji. Niektóre notyfikacje zostają celowo opóźnione przez PayU ponieważ Merchant może odbierać równolegle jedynie określoną liczbę notyfikacji (tzn. throttling). Wówczas czas opóźnienia nie wpływa na czas przetwarzania. Z czasu tego wyłączone jest również przetwarzanie po stronie banku oraz ogranizacji kartowej.
Poniżej znajdują się przykładowe powiadomienia dla zakończonego pomyślnie i anulowanego zamówienia.
- Completed order
- Cancelled order
{
"order": {
"orderId": "LDLW5N7MF4140324GUEST000P01",
"extOrderId": "Order id in your shop",
"orderCreateDate": "2012-12-31T12:00:00",
"notifyUrl": "http://tempuri.org/notify",
"customerIp": "127.0.0.1",
"merchantPosId": "{POS ID (pos_id)}",
"description": "My order description",
"currencyCode": "PLN",
"totalAmount": "200",
"buyer": {
"email": "john.doe@example.org",
"phone": "111111111",
"firstName": "John",
"lastName": "Doe",
"language": "en"
},
"payMethod": {
"type": "PBL" //or "CARD_TOKEN", "INSTALLMENTS"
},
"products": [
{
"name": "Product 1",
"unitPrice": "200",
"quantity": "1"
}
],
"status": "COMPLETED"
},
"localReceiptDateTime": "2016-03-02T12:58:14.828+01:00",
"properties": [
{
"name": "PAYMENT_ID",
"value": "151471228"
}
]
}
{
"order": {
"orderId": "LDLW5N7MF4140324GUEST000P01",
"extOrderId": "Order id in your shop",
"orderCreateDate": "2012-12-31T12:00:00",
"notifyUrl": "http://tempuri.org/notify",
"customerIp": "127.0.0.1",
"merchantPosId": "{POS ID (pos_id)}",
"description": "My order description",
"currencyCode": "PLN",
"totalAmount": "200",
"products": [
{
"name": "Product 1",
"unitPrice": "200",
"quantity": "1"
}
],
"status": "CANCELED"
}
}
Aby uzyskać więcej informacji na temat parametrów, przejdź do Referencji API.
Parametr localReceiptDateTime
jest obecny tylko przy statusie completed.
"PAYMENT_ID" jest identyfikatorem płatności, wyświetlanym na wyciągach z transakcji jako "Trans ID" oraz podczas wyszukiwania transakcji w panelu menedżerskim.
Parametr type
w sekcji payMethod
określa metodę płatności użytą w zamówieniu:
- PBL oznacza przelew online lub standardowy,
- CARD_TOKEN to płatność kartą (w tym portfele Masterpass i Visa Checkout),
- INSTALLMENTS oznacza płatność za pośrednictwem rozwiązania PayU|Raty.
Weryfikacja podpisu notyfikacji
Zamieszczony przykład pokazuje jak zweryfikować poprawność podpisu powiadomienia otrzymanego z serwera PayU.
OpenPayu-Signature:
sender=checkout;
signature=c33a38d89fb60f873c039fcec3a14743;
algorithm=MD5;
content=DOCUMENT
Postępuj według następujących instrukcji:
- Pobierz nagłówek
OpenPayU-Signature
z notyfikacji przychodzącej z serwera PayU. - Wyizoluj wartość
signature
z nagłówkaOpenPayU-Signature
. W przykładzie parametrsignature
został przypisany do zmiennejincoming_signature
.
string incoming_signature = signature_header[signature]
- Sprawdź rodzaj funkcji haszującej, którą się posłużono do wygenerowania podpisu (obecnie md5).
- Połącz treść odebranej notyfikacji oraz wartość drugiego klucza
second key
.
string concatenated = JSONnotification + second_key;
- Wyznacz oczekiwaną wartość podpisu poprzez zastosowanie wykorzystanej funkcji haszującej (np. md5) na uzyskanym łańcuchu znaków: (
expected_signature
).
string expected_signature = md5(concatenated);
- Porównaj
expected_signature
zincoming_signature
. Jeśli są one zgodne, podpis jest prawidłowy i weryfikacja zakończyła się pomyślnie. Jeśli się nie zgadzają, podpis jest nieprawidłowy.
if(expected_signature == incoming_signature){
return true; //podpis jest prawdiłowy
}else{
return 'Wrong signature' // podpis jest nieprawidłowy
}