Przejdź do głównej zawartości

Tworzenie tokena

Token jednorazowy (single-use)​

Istnieją dwa scenariusze użytkowe tokena jednorazowego:

  • jednorazowa płatność tokenem - użyj formularza Secure Form z wartością SINGLE przekazaną jako argument do metody tokenize. Umożliwi ci to tokenizację karty i wygenerowanie jednorazowego tokena, który może być użyty tylko do jednej płatności.
  • pierwsza płatność z zapisaniem karty w celu jej przyszłego użycia - użyj formularza Secure Form z wartością MULTI przekazaną jako argument do metody tokenize. Umożliwi ci to tokenizację karty i wygenerowanie jednorazowego tokena, którego użyjesz do jednorazowej płatności i zapisania danej karty (wygenerowanie tokena wielokrotnego użytku - TOKC_).

Token wielokrotnego użytku (multi-use)​

Token wielorazowy (TOKC_) tworzony jest po pierwszym użyciu tokena jednorazowego (TOK_), Google Pay Token lub Apple Pay Token. Istnieją dwa scenariusze, w których możesz utworzyć token wielokrotnego użytku:

Notatka

Kiedy karta jest zapisywana bez dokonywania rzeczywistego zakupu, ważne jest unikanie tworzenia zamówienia o kwocie innej niż 0, która później zostanie anulowana. Takie podejście jest zabronione przez systemy kart płatniczych (Visa i Mastercard). Zamiast tego musisz ustawić kwotę całkowitą na 0.

Tworzenie tokena wielokrotnego użytku podczas zakupu​

Tworzenie tokena podczas zakupu jest standardowym i najczęstszym sposobem zapisywania karty.

Wymagania

Standardowe żądanie zamówienia powinienenś rozszerzyć o sekcje buyer ipayMethod gdzie jednorazowy token (TOK_) jest użyty jako wartość parametru value.

Wartość parametru cardOnFile powinieneś ustawić na FIRST (szczegółowy opis parametru cardOnFile znajdziesz w sekcji Create an Order w naszej referencji API).

Twój POS powinien być skonfigurowany pod kątem tworzenia tokenów wielorazowych.

W sekcji buyer powinieneś przesłać parametr extCustomerId z identyfikatorem klienta w Twoim systemie. Parametr ten służy do pobierania zapisanych przez klienta metod płatności.

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": "FIRST",
      "extOrderId":"g1d5q9lpxz5rg556qiue0q",
      "products":[
         {
            "name":     "Laptop",
            "unitPrice":"15000",
            "quantity": "1"
         }
      ],
      "buyer": {
          "extCustomerId": "id_12345",
          "email": "john.doe@example.com",
          "firstName": "John",
          "lastName": "Doe",
          "language": "en"
      },
      "payMethods": {
          "payMethod": {
               "value": "TOK_1IHRPT6HKSSS3H62K0GS8pElP862",
               "type":  "CARD_TOKEN"
          }
      },
      "deviceFingerprint": "1436437b3265e8311c0495a233dcd0a7"
  }'

Szczegółowe informacje na temat parametrów, znajdziesz w sekcji Create an Order w naszej referencji API.

W ciele zamówienia wyróżniony został obiekt payMethods zawierający jednorazowy token (TOK_).

Notatka

Jeśli transakcja została przeprowadzona z wykorzystaniem Google Pay lub Apple Pay, uzyskany token może zostać wykorzystany do transakcji inicjowanych przez merchanta (cardOnFile: STANDARD_MERCHANT). Tak utworzony token nie może zostać wykorzystany do transakcji inicjowanej przez klienta (cardOnFile: STANDARD_CARDHOLDER).

POS wykorzystany w przykładzie nie ma włączonej tokenizacji.

Przykład odpowiedzi do zapisania tokena podczas zakupu
{
    "status": {
        "statusCode": "WARNING_CONTINUE_3DS",
        "severity": "WARNING"
    },
    "redirectUri": "{redirectUri}",
    "iframeAllowed": true,
    "threeDsProtocolVersion": "3DS2"
    "orderId": "ORDER_ID",
    "payMethods": {
        "payMethod": {
            "card": {
                "number": "424242******4242",
                "expirationMonth": "12",
                "expirationYear": "2017"
            },
            "type": "CARD_TOKEN",
            "value": "TOKC_KPNZVSLJUNR4DHF5NPVKDPJGMX7"
        }
    }
}

W powyższej odpowiedzi wyróżniony został wygenerowany token wielokrotnego użytku (TOKC_), który może zostać użyty do przyszłych płatności daną kartą.

Powyższa odpowiedź zakłada, że wymagane jest dodatkowe uwierzytelnienie 3DS. Więcej szczegółów znajdziesz w sekcji Obsługa 3DS.

PayU zawiadamia o statusie transakcji na adres podany w parametrze notifyUrl. Więcej szczegółów na ten temat znajdziesz w sekcji Powiadomienia.

Tworzenie tokena wielokrotnego użytku bez zakupu​

Specjalna konfiguracja

Zanim ta funkcja zostanie włączona w środowisku produkcyjnym lub testowym (sandbox) wymagana jest specjalna konfiguracja. W celu jej włączenia skontaktuj się ze swoim przedstawicielem handlowym w PayU by dowiedzieć się czy będziesz mógł korzystać z tej usługi.

W niektórych przypadkach możesz potrzebować zapisać informacje o karcie bez dokonania faktycznego zakupu przez kupującego. Ten scenariusz jest przydatny, np. gdy oferujesz bezpłatne okresy próbne lub chcesz umożliwić klientom zachowanie danych karty do wykorzystania w przyszłości bez natychmiastowej opłaty. W takich przypadkach możesz zażądać utworzenia tokena wielokrotnego użytku (TOKC_) dla określonej karty.

Tworzenie tokenów wielokrotnego użytku bez dokonywania zakupu wiąże się z pewnymi specjalnymi warunkami:

  • Standardowe zamówienie powinno być rozszerzone o sekcje buyer i payMethod gdzie jednorazowy token (TOK_) jest użyty jako wartość parametru value.

  • Wartość parametru totalAmount powinna być ustawiona na 0 (pamiętaj, że w celu zachowania spójności API nadal wymagany jest parametr currency).

  • Obiekt products nie jest wymagany.

  • Transakcje na kwotę 0 są zawsze odbierane automatycznie - nawet gdy płatności kartowe zostały skonfigurowane inaczej. Transakcje na kwotę 0 nie mogą otrzymać statusu WAITING_FOR_CONFIRMATION, zawsze przechodzą ze statusu PENDING na COMPLETED lub CANCELED

  • Transakcje na kwotę 0 nie są możliwe dla "sklepów" skonfigurowanych jako marketplace, gdzie wymagana jest sekcja shoppingCarts.

  • Wartość parametrów cardOnFile/recurring powinna być ustawiona na FIRST (szczegółowy opis parametru cardOnFile/recurring znajdziesz w sekcji Create an Order naszej referencji API).

  • Transakcje na kwotę 0 są możliwe tylko w przypadku płatności kartami.

  • Twój POS powinien być skonfigurowany do tworzenia tokenów wilokrotnego użytku.

  • Twój "sklep" w panelu merchanta powinien być skonfigurowany do przyjmowania transakcji na kwotę 0.

Przykład zapisania tokena bez zakupu
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":"0",
      "cardOnFile": "FIRST",
      "extOrderId":"4ifibqsc9nwkvanq6rcfm9",
      "buyer": {
          "extCustomerId": "id_12345",
          "email": "john.doe@example.com",
          "firstName": "John",
          "lastName": "Doe",
          "language": "en"
      },
      "payMethods": {
          "payMethod": {
               "value": "TOK_1IHRPT6HKSSS3H62K0GS8pElP862",
               "type":  "CARD_TOKEN"
          }
      },
      "deviceFingerprint": "3707dda5515f445886e3b6fff404039b"
  }'

Szczegółowe informacje na temat parametrów, zanjdziesz w sekcji Create an Order w naszej referencji API.

Wyróżnione w powyższym zamówieniu zostały:

  • parametr totalAmount z wartością 0 - zgodnie z wcześniej wspomnianymi wymaganiami,
  • obiekt payMethods z jednorazowym tokenem (TOK_), potrzebnym podczas pierwszej płatności do wygenerowania tokena wielorazowego użytku (TOKC_).

POS Wykorzystany w przykładzie nie ma włączonej tokenizacji.

Przykład odpowiedzi do zapisania tokena (TOK_) bez zakupu
{
    "status": {
        "statusCode": "WARNING_CONTINUE_3DS",
        "severity": "WARNING"
    },
    "redirectUri": "{redirectUri}",
    "iframeAllowed": true,
    "threeDsProtocolVersion": "3DS2"
    "orderId": "ORDER_ID",
    "payMethods": {
        "payMethod": {
            "card": {
                "number": "424242******4242",
                "expirationMonth": "12",
                "expirationYear": "2017"
            },
            "type": "CARD_TOKEN",
            "value": "TOKC_KPNZVSLJUNR4DHF5NPVKDPJGMX7"
        }
    }
}

W powyższej odpowiedzi wyróżniony został token wielokrotnego użytku (TOKC_), który może zostać użyty do przyszłych płatności daną kartą.

Powyższa odpowiedź zakłada również, że wymagane jest dodatkowe uwierzytelnienie 3DS. Więcej szczegółów znajdziesz w sekcji Obsługa 3DS.

PayU zawiadamia o statusie transakcji na adres podany w parametrze notifyUrl. Więcej szczegółów na ten temat znajdziesz w sekcji Powiadomienia.

Pobieranie tokenów

Zapisane tokeny wielokrotnego użytku (TOKC_) powinieneś za każdym razem pobierać z PayU zamiast kopiować je z odpowiedzi do zamówienia. Pobranie tokenów z PayU zapewni ci dostęp do dodatkowych informacji, takich jak (data ważności tokenu, status tokenu, itp.)

Na tej stronie