Informacje
Jeśli za pośrednictwem Cloud API wysyłasz żądanie anulowania płatności, konieczne jest utworzenie zadania dla urządzenia (TID), na którym pierwotnie dokonano płatności. Wysyłanie żądania anulowania płatności dokonanej na terminalu „A“ z poziomu terminala „B“ nie jest obecnie obsługiwane.
Anulowanie transakcji to podstawowa operacja płatnicza, która pozwala na anulowanie wcześniej zrealizowanej transakcji w terminie do 93 dni od daty pierwotnej transakcji. Anulowanie transakcji można przeprowadzić bez karty klienta – środki zostaną automatycznie zwrócone na kartę używaną do pierwotnej transakcji sprzedaży.
Logowanie i uwierzytelnianie
W przypadku wszystkich niepublicznych punktów końcowych wymagane jest uwierzytelnienie za pomocą tokenu JWT. Token (o okresie ważności 90 dni) można uzyskać za pośrednictwem punktu końcowego /cloud/oauth/token, podając następujące argumenty:
- Podstawowe uwierzytelnianie dla punktów końcowych tokenu (nazwa użytkownika/hasło) – zostanie udostępnione każdemu użytkownikowi.
- Nazwa użytkownika sprzedawcy – taka sama jak w przypadku GP tom
- Hasło handlowca – takie samo jak dla GP tom
- ID terminala (TID) – identyfikator terminala docelowego
- Punkt końcowy autoryzacji znajduje się pod adresem:
Uzyskanie tokenu dostępu
Przykładowe zapytanie:
POST {{apiCloudHost}}/cloud/oauth/token
Autoryzacja: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Typ zawartości: application/x-www-form-urlencoded
grant_type=password&username=jan.novak@example.com&password=ABCDEFGHIJKL&tid=999888
Przykładowa odpowiedź:
{
"access_token": "eyJh…", // token dostępu używany w uwierzytelnionych żądaniach API
"token_type": "bearer",
"refresh_token": "GciO…",
"expires_in": 3600,
"scope": "read write",
"tid": "999888",
}Odnowienie tokenu
Po wygaśnięciu ważności access_tokenu dostępny jest refresh_token.
Przykładowe zapytanie:
POST {{apiHost}}/api/oauth/token
Autoryzacja: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Typ zawartości: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=GciO…
GPTomAuth
Typ schematu bezpieczeństwa
Schemat autoryzacji HTTP
HTTP
na okaziciela
Utworzenie zadania
Wywołaj punkt końcowy POST /v1/tasks/TRANSACTION i użyj CreateCloudTaskTransactionApiRequest, wypełniając następujące dane w celu utworzenia żądania:
Zmienna
apiKey
OBOWIĄZKOWE
OBOWIĄZKOWE
porządek
OBOWIĄZKOWE
OBOWIĄZKOWE
inicjator
OBOWIĄZKOWE
OBOWIĄZKOWE
tytuł
OBOWIĄZKOWE
OBOWIĄZKOWE
printByPaymentApp
kwota
OBOWIĄZKOWE
OBOWIĄZKOWE
TipAmount
transakcjaOperacja
originTransactionId
originReferenceNum
tryb anulowania
OBOWIĄZKOWE
OBOWIĄZKOWE
transactionType*
OBOWIĄZKOWE
OBOWIĄZKOWE
currencyCode
timeToLive
Format
ciąg
ciąg
ciąg
ciąg
boolean
liczba
liczba
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
liczba całkowita
Opis
Klucz API można znaleźć bezpośrednio w aplikacji, w sekcji Konto – Cloud API. Służy on głównie do identyfikacji użytkownika podczas logowania w Cloud API.
Docelowy identyfikator TID dla danego zadania. TID = identyfikator terminala, który jest unikalny dla każdego urządzenia. Na wszystkich zainstalowanych urządzeniach można jednocześnie używać tylko jednego identyfikatora TID.
Opis inicjatora powinien być unikalny dla każdej instancji podsystemu, która może zainicjować zadanie. Przykład: „serwer XY“ lub „Kasa 1“
Nazwa zadania zrozumiała dla człowieka. Powinna zawierać jakiś element identyfikujący zadanie.
Przykład: „Faktura 37364FD – płatność“
Przykład: „Faktura 37364FD – płatność“
wartość domyślna: true
To prawda, jeśli paragon ma zostać wydrukowany na urządzeniu.
Uwaga: W przypadku telefonów komórkowych upewnij się, że drukarka Bluetooth jest podłączona.
To prawda, jeśli paragon ma zostać wydrukowany na urządzeniu.
Uwaga: W przypadku telefonów komórkowych upewnij się, że drukarka Bluetooth jest podłączona.
Kwota transakcji, która ma zostać anulowana, musi być niezerowa i zawierać miejsca po przecinku.
Nie stosuje się w przypadku anulowania.
Typ transakcji: zadanie. W przypadku transakcji „Anulowanie transakcji“ należy wpisać wartość „VOID“.
Identyfikator transakcji do anulowania. Nie jest wartością null, jeśli tryb to VOID, a anulowanie dotyczy OLDER_TRANSACTION.
Jeśli nie chcesz, aby ta wartość została wydrukowana na paragonie, pozostaw to pole puste.
Możliwe wartości: [ LAST_TRANSACTION, OLDER_TRANSACTION ], gdzie:
LAST_TRANSACTION – stosuje się wyłącznie w przypadku wcześniej autoryzowanej transakcji. Pomiędzy tym zleceniem a poprzednim zleceniem sprzedaży nie może znajdować się żadne inne zlecenie.
OLDER_TRANSACTION – stosuje się do wszystkich starszych transakcji z wyjątkiem ostatniej.
LAST_TRANSACTION – stosuje się wyłącznie w przypadku wcześniej autoryzowanej transakcji. Pomiędzy tym zleceniem a poprzednim zleceniem sprzedaży nie może znajdować się żadne inne zlecenie.
OLDER_TRANSACTION – stosuje się do wszystkich starszych transakcji z wyjątkiem ostatniej.
Możliwe wartości: [ CASH, CARD ]
3 znaki kodu waluty (ISO 4217)
Limit czasu ważności zadania w chmurze. Dozwolone są wartości z przedziału od sekund.
Przykład
333W212J3
483590
Kasa nr 12
Anulowanie 36744
false
40000
NIE UŻYWANE
VOID
FD283737333
OPCJONALNE
OLDER_TRANSACTION
KARTA
CZK
10
Treść odpowiedzi [CloudTaskDetailApiResponse]:
Możliwe kody odpowiedzi to:
Odpowiedź
RC200
RC403
RC406
RC 502
Raport
OK – Zadanie zostało zarejestrowane
Użytkownik nie ma uprawnień do rejestrowania zadania na danym terminalu
Zadanie nie jest akceptowalne dla danego terminala
Powiadomienie push nie zostało wysłane
Opis
Zadanie zostało pomyślnie utworzone i zostanie zrealizowane.
Jeśli Twoje dane logowania do API nie zgadzają się z przesłaną wartością TID (na przykład gdy właściciel TID jest inny).
Zazwyczaj ma to miejsce, gdy TID nie jest w stanie przetworzyć żądania.
Powiadomienie push nie zostało wysłane z powodu awarii usługi nadrzędnej.
Jak się zachować
Przejdź do kolejnego etapu procesu transakcji.
Sprawdź, czy podałeś prawidłowy numer TID, i spróbuj ponownie.
Sprawdź komunikat o błędzie.
Poniżej znajdują się zmienne użyte w odpowiedzi:
Zmienna
tytuł
taskId
stworzony
taskClass
status
inicjator
contextId
ładunek
exceptionId
typ
wiadomość
kontekst
Format
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
obiekt
ciąg
ciąg
ciąg
ciąg
Opis
Nazwa folderu zrozumiała dla użytkownika. Pobrano z wartości żądania.
Wewnętrzny identyfikator zadania
Data i godzina utworzenia zadania.
Klasa ładunku użytkowego. Możliwe wartości: [TRANSACTION, BATCH, DUMMY]
Stan zadania w chmurze. Możliwe wartości: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Opis inicjatora po stronie klienta. Pobrano z wartości żądania.
Identyfikator danego podmiotu docelowego, o ile istnieje (transactionId / batchId)
Treść zadania kontekstowego – w zależności od klasy zadania (taskClass)
Pseudounikalny identyfikator wyjątku. Może służyć jako „identyfikator dla pomocy technicznej“, który użytkownik może przekazać pracownikom pomocy technicznej w celu zbadania błędu.
Typ wyjątku.
Raport dotyczący wyjątku.
Kontekst wyjątku. Więcej informacji.
Przykład
Faktura nr 36744
dFd3sda
TRANSAKCJA
UTWORZONY
Kasa nr 12
{...}
FujIk6
VALIDATION_EXCEPTION
Hasło jest zbyt słabe
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
NO
NO
NO
NO
RC403
NO
NO
NO
NO
NO
NO
NO
NO
TAK
TAK
TAK
TAK
RC406
NO
NO
NO
NO
NO
NO
NO
NO
TAK
TAK
TAK
TAK
RC502
NO
NO
NO
NO
NO
NO
NO
NO
TAK
TAK
TAK
TAK
Sprawdzenie stanu torby
W kolejnym kroku należy sprawdzić stan zadania w punkcie końcowym GET /v1/tasks/{taskID} za pomocą żądania zawierającego:
Zmienna
taskId
Format
ciąg
Opis
Identyfikator zadania, który otrzymali Państwo w ramach poprzedniego kroku.
Przykład
dFd3sda
Możliwe kody zwrotne:
Odpowiedź
RC200
RC403
Raport
OK – Stan dostępnych toreb
Nie znaleziono zadania w chmurze dla bieżącego terminala.
Raport
Aktualizacja statusu zadania została pomyślnie przetworzona.
Powinniście sprawdzić swój identyfikator zadania (taskID) i ponownie przesłać prawidłową wartość.
Opis
Jeśli nie otrzymasz ostatecznego stanu (patrz poniżej), powtórz ten krok.
Sprawdź, czy podałeś prawidłowy identyfikator zadania (taskID), i spróbuj ponownie.
Zmienne w odpowiedzi:
Zmienna
tytuł
taskId
stworzony
taskClass
status
inicjator
contextID
ładunek
exceptionId
typ
wiadomość
kontekst
Format
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
Opis
Zrozumiała nazwa zadania. Pobrano z wartości podanej w żądaniu utworzenia zadania.
Wewnętrzny identyfikator zadania
Data i godzina utworzenia zadania.
Możliwe wartości: [TRANSACTION, BATCH, DUMMY]
Możliwe wartości: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Opis inicjatora po stronie klienta. Pobrano z wartości żądania.
Identyfikator danego podmiotu docelowego, o ile istnieje (transactionId / batchId)
Pseudounikalny identyfikator wyjątku. Może służyć jako „identyfikator zgłoszenia do pomocy technicznej“, który użytkownik może przekazać pracownikom pomocy technicznej w celu zbadania ewentualnego problemu.
Typ wyjątku.
Raport o wyjątku.
Kontekst wyjątku – dodatkowe informacje.
Przykład
Faktura nr 36744
dFd3sda
IN_PROGRESS
Kasa nr 12
FujIk6
VALIDATION_EXCEPTION
Hasło jest zbyt słabe
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
NO
NO
NO
NO
RC404
NO
NO
NO
NO
NO
NO
NO
NO
TAK
TAK
TAK
TAK
Zapytanie o stan zadania powinno być powtarzane do momentu uzyskania jednego z końcowych kodów odpowiedzi, którymi są:
Status
INIT_ERROR
ZAKOŃCZONE
ODWOŁANE
BŁĄD
Opis
Inicjacja procesu płatności nie powiodła się. Sprawdź otrzymany błąd.
Otrzymanie tego statusu oznacza, że zadanie zostało ukończone, a jego wynik jest dostępny.
Zadanie zostało anulowane przez użytkownika.
Podczas przetwarzania zadania wystąpił błąd.
Jak się zachować
Postępuj zgodnie z instrukcjami dotyczącymi błędu.
Możesz przejść do kolejnego kroku.
Powinniście rozpocząć nowe zadanie, ponieważ to zadanie zostało anulowane przez użytkownika.
Postępuj zgodnie z instrukcjami dotyczącymi błędu.
Można przejść do kolejnego kroku tylko wtedy, gdy odpowiedź ma status COMPLETED.
Pobranie informacji o wyniku płatności
Wiemy już, że transakcja została autoryzowana. Celem tego kroku jest uzyskanie statusu transakcji oraz jej szczegółów. Aby wysłać nowe żądanie, należy wywołać punkt końcowy GET /v1/transactions/{transactionId}, używając następujących zmiennych:
Zmienna
transactionId
Format
ciąg
Opis
ID transakcji, które uzyskujesz w poprzednich krokach.
Przykład
4414c640-2db7-11ec-910a-91880dadec20
Możliwe kody odpowiedzi to:
Odpowiedź
RC200
RC404
Raport
OK – podano szczegóły transakcji
Nie znaleziono transakcji o podanym numerze TID.
Raport
Twoja prośba została pomyślnie rozpatrzona.
Taka sytuacja ma miejsce, gdy nie znaleziono danego identyfikatora transakcji dla Twojego urządzenia.
Opis
Transakcja została zakończona!
Sprawdź identyfikator transakcji.
Odpowiedź zawiera następujące zmienne w zależności od kodu odpowiedzi:
Zmienna
wynik
responseMessage
transanctionId
transakcjaOperacja
transactionType
merchantID
porządek
currencyCode
kwota
TipAmount
cardNumber
cardDataEntry
referenceNumber
numer faktury
data
emvAppLabel
sequenceNumber
exceptionId
typ
wiadomość
kontekst
"dccData": {"status"}
Format
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
liczba
liczba
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
ciąg
Opis
Wynik transakcji, możliwe wartości [ ACCEPTED, DECLINED, CANCELLED ] gdzie:
ACCEPTED – transakcja została pomyślnie autoryzowana
DECLINED – transakcja została odrzucona z jakiegoś powodu
CANCELLED – jeśli transakcja została anulowana przez obsługę lub klienta
ACCEPTED – transakcja została pomyślnie autoryzowana
DECLINED – transakcja została odrzucona z jakiegoś powodu
CANCELLED – jeśli transakcja została anulowana przez obsługę lub klienta
Bardziej szczegółowy opis uzyskanej wartości.
Wewnętrzny identyfikator zadania
Możliwe wartości: "SALE", "VOID", "REFUND"
Operacja / rodzaj transakcji."
Operacja / rodzaj transakcji."
Możliwe wartości: "CASH", "CARD"
Tylko w przypadku transakcji kartą – numer identyfikacyjny oddziału.
ID transakcji wygenerowane przez terminal
Kod waluty (ISO 4217)
Kwota transakcji z dokładnością do 2 miejsc po przecinku (400 CZK).
Kwota napiwku podana z dokładnością do dwóch miejsc po przecinku (30 CZK).
Ukryty numer karty.
Sposób odczytu karty – pasek magnetyczny, chip lub bezstykowy.
Numer referencyjny transakcji pobrany z wartości żądania zadania: originReferenceNum
Data i godzina autoryzacji transakcji
Dane karty marki EMV pobrane z danych karty
Numer generowany po stronie GP
Pseudounikalny identyfikator wyjątku. Może służyć jako „identyfikator zgłoszenia do pomocy technicznej“, który użytkownik może przekazać pracownikom pomocy technicznej w celu zbadania sprawy.
Rodzaj wyjątku
Raport o wyjątku
Kontekst wyjątku – dodatkowe informacje.
CZ: Podaje informację, czy transakcja DCC zostanie anulowana
EN: Podaje informację, czy unieważniona transakcja została przetworzona jako DCC
EN: Podaje informację, czy unieważniona transakcja została przetworzona jako DCC
Przykład
PRZYJĘTO
null
4414c640-2db7-11ec-910a-91880dadec20
VOID
KARTA
343382001
483591
40000
-
1233
null
FD123456
2020-09-16T09:31:16.000Z
null
102304128
FujIk6
VALIDATION_EXCEPTION
Hasło jest zbyt słabe
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
CZ: Jeśli status to „ACCEPTED”, na paragonie należy umieścić następujący tekst:
EN: Jeśli ZOSTANIE TO PRZYJĘTE, należy umieścić na pokwitowaniu następujący tekst:
Kwota transakcji, waluta i kurs wymiany są takie same jak w przypadku pierwotnej transakcji.
Przeliczanie walut zapewnia firma Global Payments.
EN: Jeśli ZOSTANIE TO PRZYJĘTE, należy umieścić na pokwitowaniu następujący tekst:
Kwota transakcji, waluta i kurs wymiany są takie same jak w przypadku pierwotnej transakcji.
Przeliczanie walut zapewnia firma Global Payments.
RC 200
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
NO
NO
NO
NO
TAK
RC 404
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
TAK
TAK
TAK
TAK
NO
Jeśli zamierzają Państwo samodzielnie generować lub drukować paragon, zalecamy sprawdzenie, które pola są obowiązkowe i muszą zostać wydrukowane/wyświetlone na paragonie. Opis jest dostępny tutaj.