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:
Lokalizacja | Element danych | Typ | Stan | Opis |
Treść żądania.transakcja | oneClick | OneClick | Obowiązkowe | Obiekt definiujący płatność jednym kliknięciem. Występuje tylko w przypadku sprzedawców korzystających z One Click Payment. |
Request Body.transaction.oneClick | customerAcceptance | logiczna | Obowiązkowe | Wskazuje, 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ść żądania | tokenizacja | Tokenizacja | Obowiązkowe | Tokeny płatności klienta. Tokeny te są dostarczane na koniec udanej tokenizacji. Obecne tylko do celów tokenizacji. |
Request Body.tokenisation | tokenisationRequest | TokenisationRequest | Obowiązkowe | Podane pole w żądaniu realizacji transakcji w celu wykonania tokenizacji karty. |
Request Body.tokenisation.tokenisationRequest | tokeniseCard | logiczna | Obowiązkowe | Wskazuje, czy wymagana jest tokenizacja karty. |
Przykład żądania:
{
"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.
Lokalizacja | Element danych | Typ | Stan | Opis |
Request Body.info | deviceInfo | DeviceInfo | Obowiązkowe | Obiekt definiujący informacje o urządzeniu klienta. |
Request Body.info.deviceInfo | browserAcceptHeader | Ciąg | Opcionalnie | Nagłówek akceptacji przeglądarki. |
Request Body.info.deviceInfo | browserJavaEnabled | Ciąg | Opcionalnie | Przeglądarka z włączoną obsługą Java |
Request Body.info.deviceInfo | browserJavascriptEnabled | Ciąg | Opcionalnie | Włączona obsługa Javascript w przeglądarce |
Request Body.info.deviceInfo | browserLanguage | Ciąg | Opcionalnie | Język przeglądarki. |
Request Body.info.deviceInfo | browserColorDepth | Ciąg | Opcionalnie | Głębia kolorów przeglądarki. |
Request Body.info.deviceInfo | browserScreenHeight | Ciąg | Opcionalnie | Wysokość ekranu przeglądarki. |
Request Body.info.deviceInfo | browserScreenWidth | Ciąg | Opcionalnie | Szerokość ekranu przeglądarki. |
Request Body.info.deviceInfo | browserTZ | Ciąg | Opcionalnie | Strefa czasowa przeglądarki. |
Request Body.info.deviceInfo | browserUserAgent | Ciąg | Opcionalnie | Agent użytkownika przeglądarki. |
Request Body.info.deviceInfo | systemFamily | Ciąg | Opcionalnie | Rodzina systemów. |
Request Body.info.deviceInfo | systemVersion | Ciąg | Opcionalnie | Wesja systemu. |
Request Body.info.deviceInfo | systemArchitecture | Ciąg | Opcionalnie | Architektura systemu. |
Request Body.info.deviceInfo | deviceManufacturer | Ciąg | Opcionalnie | Producent urządzenia. |
Request Body.info.deviceInfo | deviceModel | Ciąg | Opcionalnie | Model urządzenia. |
Request Body.info.deviceInfo | deviceID | Ciąg | Opcionalnie | Unikalny identyfikator urządzenia |
Request Body.info.deviceInfo | applicationName | Ciąg | Opcionalnie | Nazwa aplikacji. |
Request Body.info.deviceInfo | applicationVersion | Ciąg | Opcionalnie | Wersja aplikacji. |
Request Body.info.deviceInfo | geoLocalization | Ciąg | Opcionalnie | Geolokalizacja. |
Request Body.info.deviceInfo | ipAddress | Ciąg | Opcionalnie | Adres IP. |
Treść żądania | oneClick | OneClick | Obowiązkowe | Obiekt definiujący płatność jednym kliknięciem. |
Request Body.oneClick | oneClickCreation | logiczna | Obowiązkowe | Obiekt 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:
{
"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
}
}
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
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:
Lokalizacja | Element danych | Typ | Stan | Opis |
Treść żądania | actionProcessed | ActionProcessed | Obowiązkowe | |
Request Body.ActionProcessed | id | Ciąg | Obowiązkowe | |
Request Body.ActionProcessed | typ | Ciąg | Obowiązkowe | Możliwe wartości to ( „THREEDS_METHOD”, „THREEDS_CHALLENGE”, „DCC”, „INSTALLMENTS” ). |
Request Body.ActionProcessed | wykonany | logiczna | Obowiązkowe | |
Treść żądania | oneClick | OneClick | Obowiązkowe | Obiekt definiujący płatność jednym kliknięciem. |
Request Body.oneClick | oneClickCreation | logiczna | Obowiązkowe | Obiekt 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:
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.
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 Code | statusMsg | Description | Action |
---|---|---|---|
HTTP-200 | Success | Success response | N/A |
HTTP-400 | Bad Request | The 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-401 | Unauthorized | On 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-403 | Forbidden | The 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-405 | Method Not Allowed | The HTTP Method used is not matching any of the API definitions available. | Please check in API Market for the correct HTTP Method. |
HTTP-429 | Too 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-500 | Internal Server Error | The 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-503 | Service Unavailable | The 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: