Menu

Zapamiętana karta bez zakupu

Karta w pliku bez zakupu oferuje możliwość bezpiecznego przechowywania danych karty płatniczej bez konieczności dokonywania natychmiastowego zakupu.

Dzięki tej weryfikacji posiadacza karty (ACV) możesz wygodnie zapisać informacje o karcie do wykorzystania w przyszłości, umożliwiając w razie potrzeby szybkie transakcje. Funkcja ta usprawnia proces dodawania kart i zarządzania nimi, zapewniając Ci elastyczność i wygodę przy zachowaniu najwyższych standardów bezpieczeństwa.

Krok 1: Utworzenie tokena

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

Aby rozpocząć korzystanie z tej funkcji, należy najpierw utworzyć token podczas tworzenia zamówienia.

Ten etap tworzenia tokena zapewnia ochronę poufnych informacji, umożliwiając jednocześnie płynne i szybkie transakcje.

Działanie 1: Utwórz zamówienie

Tworząc zamówienie, musisz uwzględnić elementy tokenizacji, jak pokazano poniżej. Należy pamiętać, że proces weryfikacji posiadacza karty konta ma zastosowanie wyłącznie w przypadku transakcji z typem płatności „AUTH”. Dodatkowo upewnij się, że wartość kwoty jest ustawiona na 0.

Adres URL żądania:

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

Nagłówki żądań:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I (...)
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Content-Type: application/json
Element DanychTypStanOpis
tokenizacjaTokenizacjaObowią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ład żądania:

Uruchom w Postmanie
{
    "merchant": {
        "terminalId": {{TerminalID}},
        "channel": "web",
        "merchantTransactionId": "1283798132" // Id mocked
    },
    "transaction": {
        "transactionTimestamp": "{{trxDatetime}}",
        "description": "Transaction for order number 4908 terminalId 100886",
        "moto": false,
        "paymentType": "AUTH",
        "amount": {
            "value": 0,
            "currency": "PLN"
        },
        "paymentMethod": [
            "CARD"
        ]
    },
    "tokenisation": {
        "tokenisationRequest": {
            "tokeniseCard": true
        }
    }
}
Działanie 2: Wygeneruj transakcję

Należy pamiętać, że poniższe żądanie wymaga nagłówka autoryzacji z transakcjąSignature 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:

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ć:

Uruchom w Postmanie
"cardInfo": {
  "PAN": "{{MCRegularCardNum}}",
  "secureCode": "{{MCRegularCardCVV}}",
  "validationDate": "{{MCRegularCardExpiry}}",
  "cardholderName": "TKN {{trxDatetime}}",
  "createToken": true
}

Powinieneś otrzymać pomyślną odpowiedź techniczną zawierającą status HTTP-200, returnStatus.statusCode=”000″ oraz, jeśli tokenizacja się powiedzie, wartość tokena, datę ważności i zamaskowane dane karty.

Sprzedawca musi zapisać wartość tokena, datę ważności i zamaskowane dane karty powiązane z danymi osobowymi klienta (na przykład powiązane z danymi logowania użytkownika).

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ź pozytywna.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 aplikacji 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 stawek 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 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 zaplanowanej 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 przepływu tokenizacji.
  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łynną realizację 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.

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
tokenizacjaTokenizacjaObowiązkowyTokeny płatności klientów. Tokeny te są dostarczane na koniec udanej tokenizacji. Obecny tylko do celów tokenizacji.
paymentTokensTokeny płatniczeObowią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ładowe żądanie powinno zawierać następujący obiekt „tokenizacji”, w którym będzie zawarty token płatności:

Uruchom w Postmanie
{
    "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}}"
      }
    ]
  }
}
Działanie 2: Wygeneruj transakcję

Następnie należy wygenerować transakcję poprzez dodanie elementu 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.

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”,
„Email„,
„Telefon komórkowy” ).

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

Uruchom w Postmanie
"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ź pozytywna.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 aplikacji 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 stawek 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 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 zaplanowanej konserwacji mogą wystąpić krótkie problemy z dostępnością.Powinieneś poczekać i spróbować ponownie później.

On this page: