Dane karty w postaci tekstowej
Jeśli spełniasz wymagania PCI i bezpośrednio zbierasz i przechowujesz dane kart swoich klientów, masz możliwość bezpiecznego przesyłania tych danych do PayU w postaci tekstowej.
Ten typ integracji jest przeznaczony tylko dla punktów sprzedaży spełniających wymogi PCI DSS i uprawnionych do przetwarzania danych kartowych po swojej stronie. Wymaga też dodatkowej konfiguracji, dlatego przed przystąpieniem do integracji skontaktuj się ze swoim opiekunem handlowym w PayU.
Rozszerzenie standardowego zamówienia
W celu przetwarzania czystych danych kartowych musisz rozszerzyć standardowe zamówienie o sekcję payMethods. Jeżeli płatność dotyczy zapisanej karty, dodatkowo musisz uwzględnić parametr cardOnFile lub recurring.
Tworzenie zamówienia z danymi karty w formie tekstowej
Dane karty muszą być wysłane w formie obiektu card zawartego w sekcji payMethods.
"payMethods": {
"payMethod": {
"card": {
"number":"5100052384536818",
"expirationMonth":"11",
"expirationYear":"2020",
"cvv":"123"
}
}
},
Szczegóły parametrów znajdziesz w sekcji Create an Order w naszej referencji API.
Parametr cardOnFile
Parametr cardOnFile powinien być używany, jeśli płatność nie jest cykliczna, ale jest dokonywana przy użyciu zapisanej karty lub karta jest zapisywana do wykorzystania w przyszłości.
cardOnFile może przyjąć jedną z trzech wartości:
- FIRST - płatność zainicjowana przez posiadacza karty, który zgodził się na jej zapisanie w celu przyszłego użycia. Możesz spodziewać się pełnego uwierzytelnienia (3D Secure i/lub CVV).
- STANDARD_CARDHOLDER - płatność zapisaną kartą zainicjowana przez posiadacza karty. W zależności od parametrów transakcji (np. wysoka kwota), możesz oczekiwać silnego uwierzytelnienia (3D Secure i/lub CVV).
- STANDARD_MERCHANT (MIT - Merchant-Initiated Transaction) - płatność zapisaną kartą zainicjowana przez sprzedawcę bez udziału posiadacza karty. Ten typ transakcji nie wymaga silnego uwierzytelnienia. Transakcja tego typu nie może być przeprowadzona, jeżeli pierwsza transakcja (FIRST) nie została zakończona pomyślnie.
Parametr cardOnFile nie może być użyty z parametrem recurring.
Jedynie w przypadku jednorazowej płatności kartą możesz pominąć parametr cardOnFile.
Dla transakcji z danymi karty w postaci tekstowej i parametrem cardOnFile ustawionym na FIRST, należy rozszerzyć sekcję payMethods.payMethod o obiekt card zawierający dane karty w formie tekstowej.
Dla kolejnych transakcji oznaczonych jako STANDARD_MERCHANT należy przekazać w sekcji payMethods.payMethod.card identyfikatory organizacji kartowej z pierwszej udanej i odebranej transakcji:
firstTransactionId- identyfikator pierwszej płatności, przekazuj go przy każdej kolejnej płatności zapisaną kartą. W przypadku Mastercard jest to tzw. Trace ID, natomiast w przypadku Visa jest to tzw. Visa Transaction Identifier.schemeTransactionId- dla zapisanych kart Mastercard należy przekazywać również dodatkowy identyfikator pierwszej płatności, którym jest tzw. Mastercard Transaction Link Identifier (TLID). Przekazuj go przy każdej kolejnej płatności zapisaną kartą. Zignoruj tę wartość dla kart Visa.
Możesz je uzyskać z danych transakcji (sekcja card.cardData) lub ze szczegółów zamówienia pobranych z parametrem with=authorization (sekcja authorization.payTypeDetails) dla pierwszej transakcji.
W przypadku kart Mastercard zapisz schemeTransactionId (TLID) zwrócony dla płatności FIRST razem z jej firstTransactionId (Trace ID) i przekazuj obie wartości we wszystkich kolejnych płatnościach z serii. Nie zastępuj zapisanego TLID wartościami schemeTransactionId zwracanymi dla kolejnych płatności.
Mastercard wprowadził nowy identyfikator transakcji Transaction Link Identifier (w skrócie TLID) oprócz aktualnie stosowanego Trace ID. TLID jest zwracany w polu schemeTransactionId dla płatności przetworzonych od 30 września 2026. Począwszy od 23 października 2026, dokonaj wszelkiej należytej staranności, aby TLID był przesyłany razem z Trace ID przy każdej kolejnej płatności zapisaną kartą. Stosuj tę regułę dla płatności typu MIT (inicjowanych przez sklep, tj. cardOnFile ustawione na STANDARD_MERCHANT lub recurring ustawione na STANDARD).
Jeśli pierwsza płatność została wykonana przed 30 września 2026, jej TLID nie jest dostępny. W takim przypadku przekaż sam Trace ID w firstTransactionId.
"payMethods": {
"payMethod": {
"card": {
"number":"5100052384536818",
"expirationMonth":"11",
"expirationYear":"2020",
"cvv":"123",
"firstTransactionId": "MCC0111LL1121",
"schemeTransactionId": "LzVYm4HlSDaYsHMFmAp4Jg"
}
}
},
"payMethods": {
"payMethod": {
"card": {
"number":"4444333322221111",
"expirationMonth":"11",
"expirationYear":"2020",
"cvv":"123",
"firstTransactionId": "483300123456789"
}
}
},
Szczegóły parametrów znajdziesz w sekcji Create an Order w naszej referencji API.
Odpowiednie ustawienie parametru cardOnFile pozwoli zwiększyć konwersję dla kart płatniczych i zagwarantować odpowiednie bezpieczeństwo transakcji.
Parametr recurring
Pole recurring oznacza zamówienie jako płatność cykliczną.
Zamówienie musi być oznaczone jako cardOnFile lub recurring; wysłanie obu pól zwróci błąd.
recurring może przyjąć jedną z dwóch wartości:
- FIRST - pierwsza transakcja z pełnym uwierzytelnieniem (użytkownik jest obecny i wyraził zgodę na warunki płatności cyklicznych),
- STANDARD - kolejna płatność cykliczna (użytkownik nie jest obecny).
Odpowiednie ustawienie parametru recurring pozwoli zwiększyć konwersję dla kart płatniczych i zagwarantować odpowiednie bezpieczeństwo transakcji.
Dla kolejnych transakcji oznaczonych jako STANDARD należy przekazać w sekcji payMethods.payMethod.card wartość firstTransactionId z pierwszej transakcji (a dla Mastercard również jej schemeTransactionId), w taki sam sposób jak opisano dla parametru cardOnFile.
Więcej informacji na temat płatności cyklicznych znajdziesz w sekcji Płatności cykliczne.
Parametr sourcePaymentFlow
Gdy integrujesz się z dostawcą cyfrowego portfela (np. Visa Mobile) i chcesz żeby Twoja płatność była rozliczona przez PayU, musisz rozszerzyć standardowe zamówienie o sekcję payMethods, w której będą się znajdować poniższe dane:
- sekcja
cardzawierająca dane instrumentu płatniczego w postaci cyfrowego portfela, - sekcja
threeDsDatazawierająca parametrtavvz wartością Token Authentication Verification Value (TAVV), - parametr
sourcePaymentFlowwskazujący źródło w postaci cyfrowego portfela, np. CLICK_TO_PAY.
Parametr sourcePaymentFlow może przyjąć jedną z następujących wartości:
- CARDS (wartość domyślna),
- APPLE_PAY,
- CLICK_TO_PAY,
- GOOGLE_PAY,
- MDES,
- VISA_MOBILE,
- VTS.
"payMethods": {
"payMethod": {
"card": {
"number": "5100052384536818",
"expirationMonth": "1",
"expirationYear": "2026"
},
"threeDsData": {
"tavv": "AgAAAHsAodvkMRYBFT8CgOpQEAA="
},
"sourcePaymentFlow": "VISA_MOBILE"
}
}
Zewnętrzny 3D Secure
W przypadku gdy nie podasz wyniku uwierzytelnienia 3D Secure (patrz Zewnętrzny 3DS), powinieneś być przygotowany na obsługę odpowiedzi ze statusem: WARNING_CONTINUE_3DS lub WARNING_CONTINUE_CVV.