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:

Przegląd prywatności

Ta strona korzysta z ciasteczek, aby zapewnić Ci najlepszą możliwą obsługę. Informacje o ciasteczkach są przechowywane w przeglądarce i wykonują funkcje takie jak rozpoznawanie Cię po powrocie na naszą stronę internetową i pomaganie naszemu zespołowi w zrozumieniu, które sekcje witryny są dla Ciebie najbardziej interesujące i przydatne.

Ściśle niezbędne ciasteczka

Niezbędne ciasteczka powinny być zawsze włączone, abyśmy mogli zapisać twoje preferencje dotyczące ustawień ciasteczek.

Jeśli wyłączysz to ciasteczko, nie będziemy mogli zapisać twoich preferencji. Oznacza to, że za każdym razem, gdy odwiedzasz tę stronę, musisz ponownie włączyć lub wyłączyć ciasteczka.