Menu

Tokenizacja

Sprzedawcy mają możliwość dostosowania się do powracających klientów, oferując możliwość zapisania danych karty do wykorzystania w przyszłości. Można to jednak zrobić wyłącznie na wyraźne żądanie klienta i za jego wyraźną zgodą. Ta wygodna funkcja ma zastosowanie w przypadku transakcji obejmujących rodzaje płatności AUTH i PURS w przypadku korzystania z karty jako metody płatności.

Krok 1: Utworzenie tokena

Działanie 1: Utwórz zamówienie
Działanie 2: Wygeneruj transakcję
Działanie 3: Wykonaj polecenie Uzyskaj status

Utworzenie tokena obejmuje kilka działań, a sprzedawca i posiadacz karty mają do odegrania kilka ról:

  1. W żądaniu realizacji transakcji sprzedawca umożliwia powracającemu klientowi zapisanie karty do wykorzystania w przyszłości i generuje formularz karty z opcją „zapisz kartę”.
  2. Żądanie płatności zawiera dane karty i opcję „zapisz kartę”, żądającą od SIBS Gateway przetworzenia płatności i, w przypadku powodzenia, utworzenia tokena karty.
  3. Odpowiedź na płatność zwraca unikalny token karty i dane karty PCI, dzięki czemu sprzedawca może zapisać je obok danych klienta użytkownikowi w ramach płatności w oparciu o token karty.
Działanie 1: Utwórz zamówienie

Proces tworzenia tokenu rozpoczyna się w momencie rozpoczęcia tworzenia zamówienia poprzez dodanie następujących elementów tokenizacji do treści istniejącego komunikatu zamówienia.

Uruchom w Postmanie

Adres URL żądania:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments

Nagłówki żądań:

Autorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I (...)
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Content-Type: application/json
Element danychTypStanOpis
tokenisationTokenizacjaObowiązkowyTokeny płatności klientów. Tokeny te są dostarczane na koniec udanej tokenizacji. Obecny tylko do celów tokenizacji.
tokenisationRequestTokenisationRequestObowiązkowyPole udostępniane w żądaniu realizacji transakcji w celu wykonania tokenizacji karty.
tokeniseCardWartość logicznaObowiązkowyWskazuje, czy zażądano tokenizacji karty.

Przykładowe żądanie zawiera informacje o tokenizacji w następujący sposób:

{
    "merchant": {
        "terminalId": 24,
        "channel": "web",
        "merchantTransactionId": "Order Id: mg990kgc5c",
        "transactionDescription": "transaction to create token",
        "shopURL": "https://mytest.e-shop.pl/"
    },
    "transaction": {
        "transactionTimestamp": "2023-05-23T07:54:20.418Z",
        "description": "transaction statement description",
        "moto": false,
        "paymentType": "AUTH",
        "amount": {
            "value": 50.5,
            "currency": "PLN"
        },
        "paymentMethod": [
            "CARD"
        ]
    },
    "tokenisation": {
        "tokenisationRequest": {
            "tokeniseCard": true
        }
    }
}
Działanie 2: Wygeneruj transakcję

Należy zauważyć, że poniższe żądanie wymaga nagłówka autoryzacji z transactionSignature zwróconą z operacji realizacji transakcji i parametrem createToken ustawionym na wartość true.

W tym żądaniu token okaziciela zostaje zastąpiony transakcją odpowiedzi na kasę transactionSignature.

Na tym etapie konieczne jest dodanie do zakupu następujących elementów:

Uruchom w Postmanie

Adres URL żądania:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/card/purchase

Nagłówki żądań:

Authorisation: Digest {transactionSignature}
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Content-Type: application/json
Element danychTypStanOpis
cardInfoInformacje o karcieObowiązkowyObiekt definiujący pola żądania operacji płatniczej.
PANCiągObowiązkowyPodstawowy numer konta (numer karty kredytowej).
secureCodeCiągOpcjonalnyKod zabezpieczający (CVV/CVC) powiązany z kartą kredytową.
validationDateISODateTimeObowiązkowyData ważności karty kredytowej.
cardholderNameCiągObowiązkowyImię i nazwisko posiadacza karty widniejące na karcie kredytowej.
createTokenWartość logicznaObowiązkowyFlaga wskazująca, czy utworzyć token do wykorzystania w przyszłości, czy nie (prawda/fałsz).

Żądanie powinno zawierać:

"cardInfo": {
  "PAN": "{{MCRegularCardNum}}",
  "secureCode": "{{MCRegularCardCVV}}",
  "validationDate": "{{MCRegularCardExpiry}}",
  "cardholderName": "TKN {{trxDatetime}}",
  "createToken": true
}
Działanie 3: Wykonaj polecenie Uzyskaj status

Status swojej transakcji możesz sprawdzić wysyłając żądanie GET.

Upewnij się, że nagłówek HTTP Authorization jest ustawiony na ten sam token okaziciela, który został użyty w początkowym zleceniu płatniczym.

Uruchom w Postmanie

Adres URL żądania:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status

Nagłówki żądań:

Authorization: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ‘<ClientId>’

Pomyślna odpowiedź techniczna składa się ze statusu HTTP-200 i returnStatus.statusCode=”000″.

Oto kilka przykładów możliwych kodów wyników:

Kod wynikustatusMsgOpisDziałanie
HTTP-200PowodzenieOdpowiedź z powodzeniem.Nie dotyczy
HTTP-400Zła prośbaŁadunek JSON nie jest zgodny z definicją API lub brakuje niektórych obowiązkowych nagłówków HTTP.Sprawdź w API Market poprawną składnię.
HTTP-401NieautoryzowanyW przypadku Autoryzacji token okaziciela jest nieprawidłowy/wygasł lub nie jest powiązany z używanym terminalem.Sprawdź w SIBS Backoffice w sekcji Poświadczenia, czy token jest ważny i w razie potrzeby utwórz nowy.
HTTP-403ZabronionyIdentyfikator klienta ustawiony w nagłówku HTTP X-IBM-Client-Id jest nieprawidłowy lub nie posiada ważnej subskrypcji interfejsu API.Sprawdź w SIBS Backoffice w SPG APP 2.0, czy ClientID jest poprawny. Jeśli problem będzie się powtarzał, skontaktuj się z pomocą techniczną SIBS Gateway w celu zresetowania ClientID.
HTTP-405Niedozwolona metodaZastosowana metoda HTTP nie jest zgodna z żadną dostępną definicją API.Sprawdź w API Market poprawną metodę HTTP.
HTTP-429Zbyt dużo próśbPrzekroczono limit szybkości wywołań API.Informacje na temat limitów połączeń mających zastosowanie do API można znaleźć w API Market.
HTTP-500Wewnętrzny błąd serweraWywołanie API nie powiodło się… i najprawdopodobniej błąd jest to po naszej stronie.Powinieneś ponowić operację, a jeśli problem będzie się powtarzał, skontaktuj się z pomocą techniczną SIBS Gateway w celu uzyskania pomocy.
HTTP-503serwis niedostępnyWywołanie API nie jest obecnie dostępne. Zwykle jesteśmy zawsze aktywni, ale podczas planowej konserwacji mogą wystąpić krótkie problemy z dostępnością.Powinieneś poczekać i spróbować ponownie później.

Krok 2: Użycie tokena

Działanie 1: Utwórz zamówienie
Działanie 2: Wygeneruj transakcję
Działanie 3: Wykonaj polecenie Uzyskaj status

Dla powracającego klienta można udostępnić opcję płatności wcześniej tokenizowaną kartą powiązaną z jego kontem w sklepie sprzedawcy, przy użyciu metody AUTH lub PURS.

Proces wykorzystania tokena można zilustrować w następujących etapach:

  1. Sprzedawca przedstawia klientowi listę dostępnych kart, wyświetlając zamaskowany PAN (częściowy numer konta) i datę ważności. Informacje te są dostarczane przez bramę dostawcy usług (SPG) podczas utworzenia tokena.
  2. Klient identyfikuje żądaną kartę z listy i wprowadza jej CVV (wartość weryfikacyjną karty).
  3. Sprzedawca przystępuje do realizacji transakcji i płatności, wykorzystując do transakcji wybraną kartę tokenizowaną.

Zapewnia to płynność transakcji poprzez bezpieczne wykorzystanie przechowywanego tokena do przetwarzania płatności.

Działanie 1: Utwórz zamówienie

Proces wykorzystania tokena rozpoczyna się w momencie rozpoczęcia tworzenia zamówienia, włączając dodatkowy element tokena do istniejącej wiadomości treści zamówienia.

Uruchom w Postmanie

Adres URL żądania:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments

Nagłówki żądań:

Autorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I (...)
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Content-Type: application/json
Element danychTypStanOpis
tokenisationTokenizacjaObowiązkowyTokeny płatności klientów. Tokeny te są dostarczane na koniec udanej tokenizacji. Obecny tylko do celów tokenizacji.
paymentTokensTokeny płatnościObowiązkowyKrotka wartości tokenu.
tokenTypeCiągObowiązkowyTyp tokena.
Możliwe wartości to (
„Karta”,
„E-mail”,
„Telefon komórkowy” ).
wartośćCiągObowiązkowyWartość tokenu.

Przykład żądania powinien zawierać następujący obiekt „tokenizacji” w celu uwzględnienia tokena płatności:

{
    "merchant": {
        "terminalId": 24,
        "channel": "web",
        "merchantTransactionId": "Order Id: bwatdhbew2",
        "transactionDescription": "transaction with 3DS",
        "shopURL": "https://mytest.e-shop.pl/"
    },
    "transaction": {
        "transactionTimestamp": "2023-05-23T08:06:07.231Z",
        "description": "transaction statement description",
        "moto": false,
        "paymentType": "AUTH",
        "amount": {
            "value": 50.5,
            "currency": "PLN"
        },
        "paymentMethod": [
            "CARD"
    ]
},
"tokenisation": {
  "paymentTokens": [
    {
      "tokenType": "Card",
      "value": "{{tokenValue}}"
      }
    ]
  }
}

Odpowiedź będzie zawierać tylko prawidłowe tokeny, które można wykorzystać w następnej akcji:

"tokenList": [
        {
            "tokenName": "TKN 2023-06-20T11:22:11.474Z",
            "tokenType": "Card",
            "value": "ODI2YWQ1MGEtMzhlNC00NjA2LTk2YTAtNjdjYTRjY2JiMDU2",
            "maskedPAN": "520474******4390",
            "expireDate": "2025-12-01T00:00:00.000Z",
            "oneClickButton": "false"
        }
Działanie 2: Wygeneruj transakcję

Następnie należy wygenerować transakcję dodając element tokeninfo.

Należy pamiętać, że poniższe żądanie wymaga nagłówka autoryzacji z podpisem transakcji zwróconym z operacji realizacji transakcji.

W tym żądaniu token okaziciela zostaje zastąpiony transakcją odpowiedzi na kasę transactionSignature.

Uruchom w Postmanie

Adres URL żądania:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/token/purchase

Nagłówki żądań:

Authorisation: Digest {transactionSignature}
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Content-Type: application/json
Element danychTypStanOpis
tokenInfoTokenInfoObowiązkowyInformacje o tokenie.
wartośćCiągObowiązkowyWartość tokenu.
secureCodeCiągOpcjonalnyBezpieczny kod tokenu.
tokenTypeCiągObowiązkowyTyp tokena.
Możliwe wartości to (
„Karta”,
„E-mail”,
„Telefon komórkowy” ).

Przykład żądania powinien zawierać następujący obiekt „tokenInfo” zawierający niezbędne informacje o tokenie:

"tokenInfo": {
  "value": "{{tokenValue}}",
  "secureCode": "536", 
  "tokenType": "Card"
}
Działanie 3: Wykonaj polecenie Uzyskaj status

Status swojej transakcji możesz sprawdzić wysyłając żądanie GET.

Upewnij się, że nagłówek HTTP Authorization jest ustawiony na ten sam token okaziciela, który został użyty w początkowym zleceniu płatniczym.

Uruchom w Postmanie

Adres URL żądania:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status

Nagłówki żądań:

Authorization: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ‘<ClientId>’

Pomyślna odpowiedź techniczna składa się ze statusu HTTP-200 i returnStatus.statusCode=”000″.

Kod wynikustatusMsgOpisDziałanie
HTTP-200PowodzenieOdpowiedź z powodzeniem.Nie dotyczy
HTTP-400Zła prośbaŁadunek JSON nie jest zgodny z definicją API lub brakuje niektórych obowiązkowych nagłówków HTTP.Sprawdź w API Market poprawną składnię.
HTTP-401NieautoryzowanyW przypadku Autoryzacji token okaziciela jest nieprawidłowy/wygasł lub nie jest powiązany z używanym terminalem.Sprawdź w SIBS Backoffice w sekcji Poświadczenia, czy token jest ważny i w razie potrzeby utwórz nowy.
HTTP-403ZabronionyIdentyfikator klienta ustawiony w nagłówku HTTP X-IBM-Client-Id jest nieprawidłowy lub nie posiada ważnej subskrypcji interfejsu API.Sprawdź w SIBS Backoffice w SPG APP 2.0, czy ClientID jest poprawny. Jeśli problem będzie się powtarzał, skontaktuj się z pomocą techniczną SIBS Gateway w celu zresetowania ClientID.
HTTP-405Niedozwolona metodaZastosowana metoda HTTP nie jest zgodna z żadną dostępną definicją API.Sprawdź w API Market poprawną metodę HTTP.
HTTP-429Zbyt dużo próśbPrzekroczono limit szybkości wywołań API.Informacje na temat limitów połączeń mających zastosowanie do API można znaleźć w API Market.
HTTP-500Wewnętrzny błąd serweraWywołanie API nie powiodło się… i najprawdopodobniej błąd jest to po naszej stronie.Powinieneś ponowić operację, a jeśli problem będzie się powtarzał, skontaktuj się z pomocą techniczną SIBS Gateway w celu uzyskania pomocy.
HTTP-503serwis niedostępnyWywołanie API nie jest obecnie dostępne. Zwykle jesteśmy zawsze aktywni, ale podczas planowej konserwacji mogą wystąpić krótkie problemy z dostępnością.Powinieneś poczekać i spróbować ponownie później.

On this page: