Informacje
W przypadku wywołania anulowania za pośrednictwem Cloud API należy utworzyć zadanie dla urządzenia (TID), na którym pierwotnie dokonano płatności. Wywołanie cofnięcia płatności dokonanej na terminalu "A" na terminalu "B" nie jest obecnie obsługiwane.
Transakcja anulowania to podstawowa operacja płatnicza, która umożliwia anulowanie wcześniej przetworzonej transakcji do 93 dni od pierwotnej transakcji. Anulowania transakcji można dokonać bez karty klienta - środki zostaną automatycznie zwrócone na kartę użytą do pierwotnej transakcji sprzedaży.
Logowanie i uwierzytelnianie
Uwierzytelnianie tokenem JWT jest wymagane dla wszystkich niepublicznych punktów końcowych. Token (o okresie ważności 90 dni) jest uzyskiwany za pośrednictwem punktu końcowego /cloud/oauth/token z następującymi argumentami:
- Podstawowe uwierzytelnianie dla punktów końcowych tokena (nazwa/hasło) - zostanie zapewnione dla każdego użytkownika.
- Nazwa użytkownika tradera - taka sama jak w przypadku GP Tom
- Hasło tradera - takie samo jak w przypadku GP Tom
- Identyfikator terminala (TID) - identyfikator terminala docelowego
- Punkt końcowy autoryzacji znajduje się pod adresem:
Uzyskiwanie tokenu dostępu
Przykładowe żądanie:
POST {{apiCloudHost}}/cloud/oauth/token
Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=jan.novak@example.com&password=ABCDEFGHIJKL&tid=999888
Przykładowa odpowiedź:
{
"access_token": "eyJh…", // access token used in authenticated API requests
"token_type": "bearer",
"refresh_token": "GciO…",
"expires_in": 3600,
"scope": "read write",
"tid": "999888",
}Odnawianie tokena
Po wygaśnięciu access_token dostępny jest refresh_token.
Przykładowe żądanie:
POST {{apiHost}}/api/oauth/token
Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=GciO…
GPTomAuth
Typ systemu zabezpieczeń
Schemat autoryzacji HTTP
HTTP
okaziciel
Tworzenie torby
Wywołaj punkt końcowy POST /v1/tasks/TRANSACTION i użyj CreateCloudTaskTransactionApiRequest z wypełnionymi następującymi informacjami, aby utworzyć żądanie:
Zmienna
apiKey
OBOWIĄZKOWE
OBOWIĄZKOWE
tid
OBOWIĄZKI
OBOWIĄZKI
inicjator
OBOWIĄZKI
OBOWIĄZKI
tytuł
OBOWIĄZKOWE
OBOWIĄZKOWE
printByPaymentApp
kwota
OBOWIĄZKOWE
OBOWIĄZKOWE
TipAmount
transactionOperation
originTransactionId
originReferenceNum
cancelMode
OBOWIĄZKOWE
OBOWIĄZKOWE
transactionType*
OBOWIĄZKOWE
OBOWIĄZKOWE
currencyCode
timeToLive (czas na życie)
Format
ciąg
ciąg
ciąg
ciąg
logiczna
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 Account-Cloud API. Służy on do rozróżniania loginów głównie w Cloud API.
Docelowy identyfikator TID dla zadania. TID = Identyfikator terminala, który jest unikalny dla każdego urządzenia. Tylko jeden identyfikator TID może być używany jednocześnie na wszystkich zainstalowanych urządzeniach.
Opis inicjatora powinien być unikalny dla każdej instancji podsystemu, która może zainicjować zadanie. Przykład: "Server XY" lub "Checkout 1".
Czytelny dla człowieka tytuł zadania. Powinien zawierać pewną identyfikację zadania.
Przykład: "Faktura 37364FD płatność"
Przykład: "Faktura 37364FD płatność"
default: true
True, jeśli paragon ma zostać wydrukowany na urządzeniu.
Uwaga: W przypadku telefonów komórkowych należy upewnić się, że drukarka Bluetooth jest podłączona.
True, jeśli paragon ma zostać wydrukowany na urządzeniu.
Uwaga: W przypadku telefonów komórkowych należy upewnić się, że drukarka Bluetooth jest podłączona.
Kwota transakcji, która ma zostać anulowana, musi być niezerowa i zawierać liczby dziesiętne.
Nie jest on używany do anulowania.
Typ transakcji worka. W przypadku transakcji "Cancellation Transaction" należy wpisać wartość "VOID".
Identyfikator transakcji do anulowania. Nie ma wartości null, jeśli tryb to VOID, a anulowanie to OLDER_TRANSACTION.
Jeśli nie chcesz drukować tej wartości na paragonie, pozostaw puste pole.
Możliwe wartości: [ LAST_TRANSACTION, OLDER_TRANSACTION ] gdzie:
LAST_TRANSACTION - używane tylko dla wcześniej autoryzowanej transakcji. Pomiędzy tym zadaniem a poprzednim zadaniem sprzedaży nie może być żadnego innego żądania.
OLDER_TRANSACTION - używane dla wszystkich starszych transakcji z wyjątkiem ostatniej transakcji.
LAST_TRANSACTION - używane tylko dla wcześniej autoryzowanej transakcji. Pomiędzy tym zadaniem a poprzednim zadaniem sprzedaży nie może być żadnego innego żądania.
OLDER_TRANSACTION - używane dla wszystkich starszych transakcji z wyjątkiem ostatniej transakcji.
Możliwe wartości: [ GOTÓWKA, KARTA ]
3 znaki dla kodu waluty (ISO 4217)
Limit wygaśnięcia zadania w chmurze. Dozwolone jest określanie wartości z drugiego interwału.
Przykład
333W212J3
483590
Kasa 12
Anulowanie 36744
fałszywy
40000
NIEUŻYWANY
VOID
FD283737333
OPCJONALNIE
STARSZA_TRANSAKCJA
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 może zarejestrować zadania na terminalu
Zadanie nie jest akceptowalne dla terminala
Powiadomienie push nie zostało wysłane
Opis
Zadanie zostało pomyślnie utworzone i zostanie przetworzone.
Jeśli poświadczenia API nie są zgodne z wysłaną wartością TID (na przykład, jeśli właściciel TID jest inny).
Zwykle ma to miejsce, gdy TID nie jest w stanie przetworzyć żądania.
Powiadomienie push nie zostało wysłane z powodu awarii usługi upstream.
Jak się zachować
Przejdź do następnego kroku w przepływie transakcji.
Sprawdź, czy wpisałeś prawidłowy identyfikator 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
Czytelna dla człowieka nazwa worka. Używana z wartości żądania.
Wewnętrzny identyfikator torby
Data i godzina utworzenia torby.
Klasa ładunkuMożliwe wartości: [TRANSACTION, BATCH, DUMMY]
Status torby w chmurze. Możliwe wartości: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR].
Opis inicjatora po stronie klienta. Używany z wartości żądania.
Identyfikator podmiotu docelowego, którego dotyczy transakcja, jeśli dotyczy (transactionId / batchId)
Treść zadania kontekstowego - w zależności od taskClass
Pseudo-unikalny identyfikator wyjątku. Może służyć jako "identyfikator wsparcia", który użytkownik może przekazać pomocy technicznej w celu zbadania błędu.
Typ wyjątku.
Raport o zwolnieniu.
Kontekst wyjątku. Dalsze informacje.
Przykład
Faktura 36744
dFd3sda
TRANSAKCJA
UTWORZONY
Kasa 12
{...}
FujIk6
VALIDATION_EXCEPTION
Zbyt słabe hasło
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
NIE
NIE
NIE
NIE
RC403
NIE
NIE
NIE
NIE
NIE
NIE
NIE
NIE
TAK
TAK
TAK
TAK
RC406
NIE
NIE
NIE
NIE
NIE
NIE
NIE
NIE
TAK
TAK
TAK
TAK
RC502
NIE
NIE
NIE
NIE
NIE
NIE
NIE
NIE
TAK
TAK
TAK
TAK
Sprawdź stan torby
V dalším kroku budete kontrolovat stav tasku na koncovém bodu GET /v1/tasks/{taskID} pomocí požadavku, který zahrnuje:
Zmienna
taskId
Format
ciąg
Opis
Identyfikator torby otrzymanej w poprzednim kroku.
Przykład
dFd3sda
Możliwe kody zwrotne:
Odpowiedź
RC200
RC403
Raport
OK - status torby dostępny
Nie znaleziono zadania w chmurze dla bieżącego terminala.
Raport
Aktualizacja statusu zadania została pomyślnie przetworzona.
Powinieneś sprawdzić swój taskID i ponownie przesłać poprawną wartość.
Opis
Jeśli nie otrzymasz statusu końcowego (patrz poniżej), powtórz ten krok.
Sprawdź, czy wpisałeś prawidłowy identyfikator zadania i spróbuj ponownie.
Zmienne 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
Czytelny dla człowieka tytuł zadania. Używany z wartości żądania utworzenia zadania.
Wewnętrzny identyfikator torby
Data i godzina utworzenia torby.
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. Używany z wartości żądania.
Identyfikator podmiotu docelowego, którego dotyczy transakcja, jeśli dotyczy (transactionId / batchId)
Pseudo-unikalny identyfikator wyjątku. Może służyć jako "identyfikator wsparcia", który użytkownik może przekazać pomocy technicznej w celu zbadania potencjalnego problemu.
Typ wyjątku.
Raport o wyjątkach.
Kontekst zwolnienia - dalsze informacje.
Przykład
Faktura 36744
dFd3sda
IN_PROGRESS
Kasa 12
FujIk6
VALIDATION_EXCEPTION
Zbyt słabe hasło
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
NIE
NIE
NIE
NIE
RC404
NIE
NIE
NIE
NIE
NIE
NIE
NIE
NIE
TAK
TAK
TAK
TAK
Zapytanie o stan torby należy powtarzać aż do 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 następnego kroku.
Należy rozpocząć nowe zadanie, ponieważ to zadanie zostało anulowane przez użytkownika.
Postępuj zgodnie z instrukcjami dotyczącymi błędu.
Możesz przejść do następnego kroku tylko wtedy, gdy odpowiedź jest w stanie COMPLETED.
Uzyskanie wyniku płatności
Nyní víme, že transakce byla autorizována. Cílem tohoto kroku je získat stav transakce a detaily transakce. Pro nový požadavek zavoláte koncový bod GET /v1/transactions/{transactionId}, kde použijete následující proměnné:
Zmienna
transactionId
Format
ciąg
Opis
Identyfikator transakcji uzyskany 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 dla bieżącego identyfikatora TID.
Raport
Pomyślna odpowiedź na żądanie.
Ten stan występuje, gdy identyfikator transakcji nie został znaleziony dla 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
transactionOperation
transactionType
merchantID
porządek
currencyCode
kwota
TipAmount
cardNumber
cardDataEntry
referenceNumber
invoiceNumber
data
emvAppLabel
sequenceNumber
exceptionId
typ
wiadomość
kontekst
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
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 operatora 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 operatora lub klienta
Bardziej szczegółowy opis wartości wynikowej.
Wewnętrzny identyfikator zadania
Możliwe wartości: ""SALE"" ""VOID"" ""REFUND""
Typ operacji / transakcji".
Typ operacji / transakcji".
Możliwe wartości "GOTÓWKA" "KARTA"
Tylko dla transakcji kartą - ID oddziału.
Identyfikator transakcji utworzonej przez terminal
Kod waluty (ISO 4217)
Kwota transakcji z 2 miejscami po przecinku (400 CZK).
Kwota napiwku wprowadzona z dokładnością do 2 miejsc po przecinku (30 CZK).
Zamaskowany numer karty.
Metoda ładowania karty - magstripe, chip lub zbliżeniowa.
Numer referencyjny transakcji pobrany z wartości zadania żądania: originReferenceNum
Data i godzina autoryzacji transakcji
Marka EMV karty pobrana z danych karty
Numer wygenerowany po stronie GP
Pseudo-unikalny identyfikator wyjątku. Może służyć jako "identyfikator pomocy technicznej", który użytkownik może przekazać pomocy technicznej do zbadania.
Typ wyjątku
Raport o wyjątkach
Kontekst zwolnienia - dalsze informacje.
Przykład
PRZYJĘTY
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
Zbyt słabe hasło
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC 200
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
TAK
NIE
NIE
NIE
NIE
RC 404
NIE
NIE
NIE
NIE
NIE
NIE
NIE
NIE
NIE
NIE
NIE
NIE
NIE
NIE
NIE
NIE
NIE
TAK
TAK
TAK
TAK
Jeśli będziesz generować lub drukować paragon po swojej stronie, zalecamy sprawdzenie, które pola są obowiązkowe i muszą być drukowane/wyświetlane na paragonie. Opis jest dostępny tutaj.