Menu

Zapisanie danych karty

Gdy sprzedawca proponuje zalogowanemu posiadaczowi karty utworzenie płatności jednym kliknięciem, prezentowane są obowiązujące warunki.

Jeśli posiadacz karty zaakceptuje i poda dane swojej karty, musi przeprowadzić silne uwierzytelnienie klienta 3D Secure zgodnie z wymogami. Po pomyślnym uwierzytelnieniu karta jest tokenizowana i rejestrowana w Międzynarodowym Systemie Płatności (IPS). Token jest następnie dostarczany do sprzedawcy i rejestrowany jako karta w pliku.

Jak to działa

Aby wykonać płatność z autoryzacją 3DS, najpierw utwórz zamówienie zgodnie z instrukcjami zawartymi w Przewodniku integracji API (Full-Code).

Należy pamiętać, że do żądania zamówienia należy dołączyć dodatkowe parametry OneClick i Tokenization, jak pokazano poniżej:

LokalizacjaElement danychTypStanOpis
Treść żądania.transakcjaoneClickOneClickObowiązkoweObiekt definiujący płatność jednym kliknięciem. Występuje tylko w przypadku sprzedawców korzystających z One Click Payment.
Request Body.transaction.oneClickcustomerAcceptancelogicznaObowiązkoweWskazuje, czy Klient zaakceptował Regulamin usługi One Click Payment w celu kontynuowania płatności.
Ma wartość „True„, jeśli Warunki płatności jednym kliknięciem zostały przedstawione przez Sprzedawcę i wyraźnie zaakceptowane przez Klienta. W przeciwnym razie musi mieć wartość „False„. W przypadku braku należy przyjąć wartość „False”.
Treść żądaniatokenizacjaTokenizacjaObowiązkoweTokeny płatności klienta. Tokeny te są dostarczane na koniec udanej tokenizacji. Obecne tylko do celów tokenizacji.
Request Body.tokenisationtokenisationRequestTokenisationRequestObowiązkowePodane pole w żądaniu realizacji transakcji w celu wykonania tokenizacji karty.
Request Body.tokenisation.tokenisationRequesttokeniseCardlogicznaObowiązkoweWskazuje, czy wymagana jest tokenizacja karty.

Przykład żądania:

Uruchom w Postmanie
	{
	    "merchant": {
	        "terminalId": {{TerminalID}},
	        "channel": "web",
	        "merchantTransactionId": "Order Id: r7cxvi0saj"
	    },
	    "transaction": {
	        "transactionTimestamp": "{{trxDatetime}}",
	        "description": "Transaction for order number 4908 terminalId 100886",
	        "moto": false,
	        "paymentType": "PURS",
	        "amount": {
	            "value": 50.50,
	            "currency": "PLN"
	        },
	        "paymentMethod": [
	            "CARD"
	        ],
	        "oneClick": {
	            "customerAcceptance": true
	        }
	    },
	    "tokenisation": {
	        "tokenisationRequest": {
	            "tokeniseCard": true
	        }
	    }
	}

Następnie możesz przystąpić do dokonania płatności.

Do żądania zakupu należy dołączyć dodatkowe parametry DeviceInfo i OneClick, jak pokazano poniżej.

LokalizacjaElement danychTypStanOpis
Request Body.infodeviceInfoDeviceInfoObowiązkoweObiekt definiujący informacje o urządzeniu klienta.
Request Body.info.deviceInfobrowserAcceptHeaderCiągOpcionalnieNagłówek akceptacji przeglądarki.
Request Body.info.deviceInfobrowserJavaEnabledCiągOpcionalniePrzeglądarka z włączoną obsługą Java
Request Body.info.deviceInfobrowserJavascriptEnabledCiągOpcionalnieWłączona obsługa Javascript w przeglądarce
Request Body.info.deviceInfobrowserLanguageCiągOpcionalnieJęzyk przeglądarki.
Request Body.info.deviceInfobrowserColorDepthCiągOpcionalnieGłębia kolorów przeglądarki.
Request Body.info.deviceInfobrowserScreenHeightCiągOpcionalnieWysokość ekranu przeglądarki.
Request Body.info.deviceInfobrowserScreenWidthCiągOpcionalnieSzerokość ekranu przeglądarki.
Request Body.info.deviceInfobrowserTZCiągOpcionalnieStrefa czasowa przeglądarki.
Request Body.info.deviceInfobrowserUserAgentCiągOpcionalnieAgent użytkownika przeglądarki.
Request Body.info.deviceInfosystemFamilyCiągOpcionalnieRodzina systemów.
Request Body.info.deviceInfosystemVersionCiągOpcionalnieWesja systemu.
Request Body.info.deviceInfosystemArchitectureCiągOpcionalnieArchitektura systemu.
Request Body.info.deviceInfodeviceManufacturerCiągOpcionalnieProducent urządzenia.
Request Body.info.deviceInfodeviceModelCiągOpcionalnieModel urządzenia.
Request Body.info.deviceInfodeviceIDCiągOpcionalnieUnikalny identyfikator urządzenia
Request Body.info.deviceInfoapplicationNameCiągOpcionalnieNazwa aplikacji.
Request Body.info.deviceInfoapplicationVersionCiągOpcionalnieWersja aplikacji.
Request Body.info.deviceInfogeoLocalizationCiągOpcionalnieGeolokalizacja.
Request Body.info.deviceInfoipAddressCiągOpcionalnieAdres IP.
Treść żądaniaoneClickOneClickObowiązkoweObiekt definiujący płatność jednym kliknięciem.
Request Body.oneClickoneClickCreationlogicznaObowiązkoweObiekt definiujący płatność jednym kliknięciem. Wskazuje, czy klient żąda utworzenia płatności jednym kliknięciem. Brak wskazuje wartość „False„.

Przykład żądania:

Uruchom w Postmanie
	{
	    "info": {
	        "deviceInfo": {
	            "browserAcceptHeader": "application/json, text/plain, */*",
	            "browserJavaEnabled": "false",
	            "browserLanguage": "en",
	            "browserColorDepth": "24",
	            "browserScreenHeight": "1080",
	            "browserScreenWidth": "1920",
	            "browserTZ": "-60",
	            "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
	            "geoLocalization": "Lat: 38.7350528 | Long: -9.2143616",
	            "systemFamily": "Windows",
	            "systemVersion": "Windows",
	            "deviceID": "498bfd4c3a3645b38667a7037b616c18",
	            "applicationName": "Chrome",
	            "applicationVersion": "106"
	        },
	        "customerInfo": [
	            {
	                "key": "customerName",
	                "value": "User X"
	            },
	            {
	                "key": "customerEmail",
	                "value": "testingemail@gmail.com"
	            }
	        ]
	    },
	    "cardInfo": {
	        "PAN": "{{MC3DSCardNum}}",
	        "secureCode": "{{MC3DSCardCVV}}",
	        "validationDate": "{{MC3DSCardExpiry}}",
	        "cardholderName": "TKN {{trxDatetime}}",
	        "createToken": true
	    },
	    "oneClick": {
	        "oneClickCreation": true
	    }
	}
Notification

Podczas przechowywania danych karty należy pamiętać, że konieczne będzie przejście przez Challenge Flow opisany na stronie 3D Secure. Proces ten pomaga zapewnić bezpieczeństwo przechowywanych informacji i zabezpiecza przed nieuprawnionym wykorzystaniem.

Otrzymasz odpowiedź zawierającą w wiadomości status płatności. Informuje on, czy transakcja została zaakceptowana, odrzucona, nadal oczekuje na ostateczny wynik lub wymaga dodatkowych działań.

  • Sukces: Zakup został pomyślnie przetworzony, a klient został obciążony.
  • Odrzucono: Zakup został odrzucony.
  • W toku: Ostateczny wynik zakupu nie jest jeszcze znany. Konieczne będzie zapytanie o status tej transakcji, dopóki nie osiągnie ona stanu końcowego lub użytkownik nie zdecyduje się jej anulować.
  • Częściowy: zakup został częściowo zaakceptowany, ale do jego zakończenia wymagane są dodatkowe działania (np. uwierzytelnienie 3D-Secure). Element actionResponse zawiera instrukcje dotyczące dalszego postępowania.

Jeśli otrzymany status płatności „Częściowy„, oznacza to, że przed ponownym wysłaniem wniosku o płatność kartą należy wysłać dodatkowe żądanie uwierzytelnienia 3DS (Challenge Flow).

Odpowiedź będzie również zawierać element actionResponse z informacjami o tym, jak postępować, jak pokazano w poniższym przykładzie.

Zapisz identyfikator actionResponse.id, aby użyć go do ponownego przesłania żądania płatności po zakończeniu uwierzytelniania 3DS.

Przykład odpowiedzi na akcję:

"actionResponse": {
"id": "be9b2788-3061-467c-b2a5-a36ad17f085c",
"type": "THREEDS_CHALLENGE",
"data": {
"url": "https://api-aws.sibs.ro/sandbox/sibs/public/acsSample",
"params": [
{
"name": "creq",
"data": "eyJ0aHJlZURTU(...)"
}
]
}
}

Musisz wykonać trzy dodatkowe czynności:

Działanie 1: Przekierowanie posiadacza karty do ACS w celu uwierzytelnienia 3DS
Działanie 2: Ponowne przesłanie transakcji do ostatecznej autoryzacji
Działanie 3: Wykonanie Uzyskania Statusu
Działanie 1: Przekierowanie posiadacza karty do ACS w celu uwierzytelnienia 3DS

Przeglądarka klienta musi zostać przekierowana przez POST do adresu URL serwera kontroli dostępu 3DS (ACS) wskazanego przez actionResponse.data.url przy użyciu actionResponse.data.params jako parametrów żądania.

Po zakończeniu uwierzytelniania przeglądarka posiadacza karty jest przekierowywana z powrotem do źródła.

Przykład przekierowania do ACS w Javascript

Uruchom w Postmanie
POST "https://api-aws.sibs.ro/sandbox/sibs/public/acsSample"
creq: eyJ0aHJlZURTU(...)
Działanie 2: Ponowne przesłanie transakcji do ostatecznej autoryzacji

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

W tym żądaniu zakupu należy uwzględnić dodatkowe parametry ActionProcessed i OneClick, jak pokazano poniżej:

LokalizacjaElement danychTypStanOpis
Treść żądaniaactionProcessedActionProcessedObowiązkowe
Request Body.ActionProcessedidCiągObowiązkowe
Request Body.ActionProcessedtypCiągObowiązkoweMożliwe wartości to (
„THREEDS_METHOD”,
„THREEDS_CHALLENGE”, „DCC”,
„INSTALLMENTS” ).
Request Body.ActionProcessedwykonanylogicznaObowiązkowe
Treść żądaniaoneClickOneClickObowiązkoweObiekt definiujący płatność jednym kliknięciem.
Request Body.oneClickoneClickCreationlogicznaObowiązkoweObiekt definiujący płatność jednym kliknięciem. Wskazuje, czy klient żąda utworzenia płatności jednym kliknięciem. Brak wskazuje wartość „False„.

Przykład żądania:

Uruchom w Postmanie

Adres URL żądania:

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

Nagłówki żądań:

Authorization: ‘Digest <transactionSignature>’
X-IBM-Client-Id: ‘<ClientId>’
Content-Type: application/json
	    "info": {
	        "deviceInfo": {
	            "browserAcceptHeader": "application/json, text/plain, */*",
	            "browserJavaEnabled": "false",
	            "browserLanguage": "en",
	            "browserColorDepth": "24",
	            "browserScreenHeight": "1080",
	            "browserScreenWidth": "1920",
	            "browserTZ": "-60",
	            "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
	            "geoLocalization": "Lat: 38.7350528 | Long: -9.2143616",
	            "systemFamily": "Windows",
	            "systemVersion": "Windows",
	            "deviceID": "498bfd4c3a3645b38667a7037b616c18",
	            "applicationName": "Chrome",
	            "applicationVersion": "106"
	        },
	        "customerInfo": [
	            {
	                "key": "customerName",
	                "value": "User X"
	            },
	            {
	                "key": "customerEmail",
	                "value": "testingemail@gmail.com"
	            }
	        ]
	    },
	    "cardInfo": {
	        "PAN": "{{MC3DSCardNum}}",
	        "secureCode": "{{MC3DSCardCVV}}",
	        "validationDate": "{{MC3DSCardExpiry}}",
	        "cardholderName": "TKN {{trxDatetime}}",
	        "createToken": true
	    },
	    "oneClick": {
	        "oneClickCreation": true
	    },
	    "actionProcessed": {
	        "id": "{{actionId}}",
	        "type": "THREEDS_CHALLENGE",
	        "executed": true
	    }
	}

Oczekiwana odpowiedź:

Jak widzieliśmy wcześniej, paymentStatus w odpowiedzi informuje o tym, czy sama transakcja została odrzucona, przetworzona pomyślnie, czy też wymaga jeszcze innego działania.

Jeśli status płatności to „Częściowa„, należy wykonać te same kroki, co poprzednio, zaczynając od Działania 1.

Działanie 3: Wykonanie Uzyskania Statusu

Po pełnym przetworzeniu płatności można sprawdzić status transakcji, wysyłając żądanie GET.

Upewnij się, że nagłówek HTTP Authorization jest ustawiony na ten sam token Bearer, 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>’
Content-Type: application/json

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:

Result CodestatusMsgDescriptionAction
HTTP-200SuccessSuccess responseN/A
HTTP-400Bad RequestThe JSON payload is not matching the API definition or some mandatory HTTP headers are missing.Please check in API Market for the correct syntax.
HTTP-401UnauthorizedOn the Authorization, Bearer token is invalid/expired or not associated with the Terminal used.Please check in SIBS Backoffice under the Credentials if the token is valid and create a new one if needed.
HTTP-403ForbiddenThe ClientID set on the X-IBM-Client-Id HTTP header is not valid or does not possess a valid subscription to the API.Please check in SIBS Backoffice under the SPG APP 2.0 if the ClientID is correct. If the problem persists contact SIBS Gateway support for a ClientID reset.
HTTP-405Method Not AllowedThe HTTP Method used is not matching any of the API definitions available.Please check in API Market for the correct HTTP Method.
HTTP-429Too Many Requests
The API calls rate limit has been exceeded.Please check in API Market for information on the rate limits that apply to the API.
HTTP-500Internal Server ErrorThe API call has failed… and its most likely on our side.You should retry the operation, and if the problem persists contact SIBS Gateway support for assistance.
HTTP-503Service UnavailableThe API call is not currently available. Usually we are always on, but short availability issues may occur during scheduled maintenance.You should wait and try again later.

Co dalej?

Sprawdź kolejny krok na:

On this page: