Informace
Pokud skrze Cloud API voláte storno platby, je nezbytné vytvořit task pro zařízení (TID), kde byla platba původně provedena. Volání storna platby provedené na terminálu „A“ na terminálu „B“ není aktuálně podporováno.
Storno transakce je základní platební operace, která umožňuje zrušit dříve zpracovanou transakci až 93 dnů od původní transakce. Zrušení transakce lze provést bez zákaznické karty – prostředky budou automaticky vráceny na kartu použitou pro původní transakci typu prodej.
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 bezpečnostního schématu
Schéma autorizace 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
API key naleznete přímo v aplikaci v sekci Účet-Cloud API. Používá se k rozlišení přihlášení hlavně v 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.
Popis iniciátoru by měl být jedinečný pro každou instanci subsystému, která může iniciovat úlohu. Příklad: „server XY“ nebo „Pokladna 1“
Nazwa zadania zrozumiała dla człowieka. Powinna zawierać jakiś element identyfikujący zadanie.
Příklad: „Faktura 37364FD platba“
Příklad: „Faktura 37364FD platba“
výchozí hodnota: true
To prawda, jeśli paragon ma zostać wydrukowany na urządzeniu.
Poznámka: U mobilních telefonů se ujistěte, že je připojena Bluetooth tiskárna.
To prawda, jeśli paragon ma zostać wydrukowany na urządzeniu.
Poznámka: U mobilních telefonů se ujistěte, že je připojena Bluetooth tiskárna.
Částka transakce, která má být zrušena, musí být nenulová a zahrnuje desetinná místa.
Pro storno se nepoužívá.
Typ transakce tasku. U transakce „Storno transakce“ vyplníte hodnotu „VOID“.
Identyfikator transakcji do anulowania. Nie jest wartością null, jeśli tryb to VOID, a anulowanie dotyczy OLDER_TRANSACTION.
Nechcete-li tuto hodnotu tisknout na účtenku, ponechte prázdné.
Možné hodnoty: [ LAST_TRANSACTION, OLDER_TRANSACTION ] kde:
LAST_TRANSACTION - používá se pouze pro dříve autorizovanou transakci. Mezi tímto úkolem a předchozím prodejním úkolem nemůže být žádný jiný požadavek.
OLDER_TRANSACTION – používá se pro všechny starší transakce kromě poslední transakce.
LAST_TRANSACTION - používá se pouze pro dříve autorizovanou transakci. Mezi tímto úkolem a předchozím prodejním úkolem nemůže být žádný jiný požadavek.
OLDER_TRANSACTION – používá se pro všechny starší transakce kromě poslední transakce.
Možné hodnoty: [ CASH, CARD ]
3 znaky pro kód měny (ISO 4217)
Limit pro vypršení platnosti cloudové úlohy. Je povoleno zadat hodnoty z intervalu <10 až 172800> sekund.
Przykład
333W212J3
483590
Kasa nr 12
Storno 36744
false
40000
NIE UŻYWANE
VOID
FD283737333
OPTIONAL
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.
Třída užitečného zatíženíMožné hodnoty: [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
invoiceNumber
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.
Způsob načtení karty - mag.proužek, čip nebo contactless.
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: Udává informaci, zda se stornuje DCC transakce
EN: Gives iformation whether voided transaction was processed as DCC
EN: Gives iformation whether voided transaction was processed as 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: Pokud ACCEPTED, je potřeba na účtenku dát text:
EN: If ACCEPTED, you need to put on your receit following text:
The transaction amount, currency and the exchange rate are the same as for the original transaction.
The currency conversion is provided by Global Payments.
EN: If ACCEPTED, you need to put on your receit following text:
The transaction amount, currency and the exchange rate are the same as for the original transaction.
The currency conversion is provided by 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.