0 CZK
Přihlášení / Registrace
Wyświetl kategorie

Sprzedaż transakcji

Transakcja sprzedaży to podstawowa operacja płatnicza, która przenosi określoną kwotę z konta bankowego posiadacza karty na konto sprzedawcy.

Jeśli chodzi o proces płatności, procedura wygląda następująco:

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:

Ten sposób uwierzytelniania jest taki sam dla wszystkich terminali.

Uzyskanie tokenu dostępu

Przykładowe zapytanie:

POST {{apiCloudHost}}/cloud/oauth/token
Autoryzacja: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Typ zawartości: application/x-www-form-urlencoded

(Dane dotyczące autoryzacji i typu treści są zawsze takie same dla wszystkich klientów – proszę użyć tych samych danych, co w przykładzie. W polu „grant_type” należy następnie wpisać unikalne dane klienta).

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 / Security scheme
HTTP
Schemat autoryzacji HTTP / HTTP authorization scheme
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
Format
Opis
Przykład
apiKey
OBOWIĄZKOWE
ciąg
Klucz API można znaleźć bezpośrednio w aplikacji GP tom, w sekcji Konto – Cloud API. Służy on głównie do identyfikacji użytkownika podczas logowania w Cloud API. Klucz API jest unikalny dla każdej firmy.
333W212J3
porządek
OBOWIĄZKOWE
ciąg
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.
483590
inicjator
OBOWIĄZKOWE
ciąg
Opis inicjatora powinien być unikalny dla każdej instancji podsystemu, która może zainicjować zadanie. Przykład: „serwer XY“ lub „Kasa 1“
Kasa nr 12
tytuł
OBOWIĄZKOWE
ciąg
Nazwa zadania zrozumiała dla człowieka. Powinna zawierać jakiś element identyfikujący zadanie.
Przykład: „Faktura 37364FD“
Faktura nr 36744
printByPaymentApp
boolean
domyślnie: true
To prawda, 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.
false
kwota
OBOWIĄZKOWE
liczba
Kwota transakcji musi być niezerowa i zawierać miejsca po przecinku. W przypadku transakcji o wartości 50 EUR należy wpisać wartość „5000“.
40000
TipAmount
liczba
Wysokość napiwku. Jeśli napiwek wynosi 3 EUR, należy wpisać wartość „300“.
0
transakcjaOperacja
OBOWIĄZKOWE
ciąg
Typ transakcji zadania. W przypadku transakcji „Sale“ należy wpisać wartość „SALE“.
WYPRZEDAŻ
originTransactionId
ciąg
Identyfikator transakcji do anulowania. Nie jest wartością null, jeśli tryb to VOID, a anulowanie dotyczy OLDER_TRANSACTION.
NIE UŻYWANE
originReferenceNum
ciąg
Numer referencyjny, np. numer faktury – wprowadź dowolną wartość o długości do 20 znaków, która będzie widoczna w zestawieniach i pozwoli zidentyfikować płatność po Twojej stronie.
FD123456
tryb anulowania
ciąg
Tryb anulowania, nie null, jeśli typ transakcji to VOID
Możliwe wartości: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
NIE UŻYWANE
transactionType*
OBOWIĄZKOWE
ciąg
Możliwe wartości: [ CASH, CARD, ACCOUNT_PAYMENT, BLIK_PAYMENT, PAYMENT_GATEWAY ]
KARTA
currencyCode
ciąg
3 symbole waluty (zgodnie z normą ISO 4217)
CZK
preferableReceiptType
ciąg
Wstępnie wybrany sposób wysłania paragonu: [ EMAIL, TELEFON, QR, DRUK ]
EMAIL
e-mail
ciąg
Adres e-mail klienta
support@gptom.com
telefon
ciąg
Numer telefonu klienta
+420123456789
TipCollect
boolean
domyślnie: false
Jeśli ustawiono wartość true, najpierw wyświetli się ekran wprowadzania napiwku w GP tom.
Aby wyświetlić ten ekran, należy również włączyć funkcję napiwków w aplikacji
timeToLive
liczba całkowita
Limit czasu ważności zadania w chmurze. Dopuszczalne są wartości z przedziału od 10 do 172800 sekund.
10

Treść odpowiedzi [CloudTaskDetailApiResponse]:

Możliwe kody odpowiedzi to:

Odpowiedź
Raport
Opis
Jak się zachować
RC200
OK – Zadanie zostało zarejestrowane
Zadanie zostało pomyślnie utworzone i zostanie zrealizowane.
Przejdź do kolejnego etapu procesu transakcji.
RC401
Nie zidentyfikowano
Jeśli nie przeprowadzono uwierzytelnienia za pomocą terminala.
Przeprowadź proces uwierzytelniania (patrz krok powyżej).
RC403
Użytkownik nie ma uprawnień do rejestrowania zadania na danym terminalu
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).
Sprawdź, czy podałeś prawidłowy numer TID, i spróbuj ponownie.
RC406
Zadanie nie jest akceptowalne dla danego terminala
Zazwyczaj ma to miejsce, gdy TID nie jest w stanie przetworzyć żądania.
Sprawdź komunikat o błędzie.
RC 502
Powiadomienie push nie zostało wysłane
Powiadomienie push nie zostało wysłane z powodu awarii usługi nadrzędnej.

Poniżej znajdują się zmienne użyte w odpowiedzi:

Zmienna
Format
Opis
Przykład
RC200
RC403
RC406
RC502
tytuł
ciąg
Nazwa folderu zrozumiała dla użytkownika. Pobrano z wartości żądania.
Faktura nr 36744
TAK
NO
NO
NO
taskId
ciąg
Wewnętrzny identyfikator zadania
dFd3sda
TAK
NO
NO
NO
stworzony
ciąg
Data i godzina utworzenia zadania.
TAK
NO
NO
NO
taskClass
ciąg
Klasa ładunku użytkowego. Możliwe wartości: [TRANSACTION, BATCH, VOID]
TRANSAKCJA
TAK
NO
NO
NO
status
ciąg
Stav cloudového tasku. Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, COMPLETED, CANCELLED, ERROR]
UTWORZONY
TAK
NO
NO
NO
inicjator
ciąg
Opis inicjatora po stronie klienta. Pobrano z wartości żądania.
Kasa nr 12
TAK
NO
NO
NO
contextId
ciąg
Identyfikator danego podmiotu docelowego, o ile istnieje (transactionId / batchId)
TAK
NO
NO
NO
ładunek
obiekt
Treść zadania kontekstowego – w zależności od klasy zadania (taskClass)
{...}
TAK
NO
NO
NO
exceptionId
ciąg
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.
FujIk6
NO
TAK
TAK
TAK
typ
ciąg
Typ wyjątku.
VALIDATION_EXCEPTION
NO
TAK
TAK
TAK
wiadomość
ciąg
Raport dotyczący wyjątku.
Hasło jest zbyt słabe
NO
TAK
TAK
TAK
kontekst
ciąg
Kontekst wyjątku. Więcej informacji.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
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
Format
Opis
Przykład
taskId
ciąg
Identyfikator zadania, który otrzymali Państwo w ramach poprzedniego kroku.
dFd3sda

Możliwe kody zwrotne:

Odpowiedź
Raport
Raport
Opis
RC200
OK – Stan dostępnych toreb
Aktualizacja statusu zadania została pomyślnie przetworzona.
Jeśli nie otrzymasz ostatecznego stanu (patrz poniżej), powtórz ten krok.
RC403
Nie znaleziono zadania w chmurze dla bieżącego terminala.
Powinniście sprawdzić swój identyfikator zadania (taskID) i ponownie przesłać prawidłową wartość.
Sprawdź, czy podałeś prawidłowy identyfikator zadania (taskID), i spróbuj ponownie.

Zmienne w odpowiedzi:

Zmienna
Format
Opis
Przykład
RC200
RC404
tytuł
ciąg
Zrozumiała nazwa zadania. Pobrano z wartości podanej w żądaniu utworzenia zadania.
Faktura nr 36744
TAK
NO
taskId
ciąg
Wewnętrzny identyfikator zadania
dFd3sda
TAK
NO
stworzony
ciąg
Data i godzina utworzenia zadania.
TAK
NO
taskClass
ciąg
Możliwe wartości: [TRANSACTION, BATCH, DUMMY]
TAK
NO
status
ciąg
Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, COMPLETED, CANCELLED, ERROR]
ZAKOŃCZONE
TAK
NO
inicjator
ciąg
Opis inicjatora po stronie klienta. Pobrano z wartości żądania.
Kasa nr 12
TAK
NO
contextID
ciąg
Identyfikator danego podmiotu docelowego, o ile istnieje (transactionId / batchId)
TAK
NO
ładunek
TAK
NO
exceptionId
ciąg
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.
FujIk6
NO
TAK
typ
ciąg
Typ wyjątku.
VALIDATION_EXCEPTION
NO
TAK
wiadomość
ciąg
Raport o wyjątku.
Hasło jest zbyt słabe
NO
TAK
kontekst
ciąg
Kontekst wyjątku – dodatkowe informacje.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
TAK

Zapytanie o stan zadania powinno być powtarzane do momentu uzyskania jednego z końcowych kodów odpowiedzi, którymi są:

Status
Opis
Jak się zachować
INIT_ERROR
Inicjacja procesu płatności nie powiodła się. Sprawdź otrzymany błąd.
Postępuj zgodnie z instrukcjami dotyczącymi błędu.
ZAKOŃCZONE
Otrzymanie tego statusu oznacza, że zadanie zostało ukończone, a jego wynik jest dostępny.
Możesz przejść do kolejnego kroku.
ODWOŁANE
Zadanie zostało anulowane przez użytkownika.
Powinniście rozpocząć nowe zadanie, ponieważ to zadanie zostało anulowane przez użytkownika.
BŁĄD
Podczas przetwarzania zadania wystąpił błąd.
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
Format
Opis
Przykład
contextId
ciąg
ID transakcji, które uzyskujesz w poprzednich krokach.

Możliwe kody odpowiedzi to:

Odpowiedź
Raport
Raport
Opis
RC200
OK – podano szczegóły transakcji
Twoja prośba została pomyślnie rozpatrzona.
Transakcja została zakończona!
RC404
Nie znaleziono transakcji o podanym numerze TID.
Taka sytuacja ma miejsce, gdy nie znaleziono danego identyfikatora transakcji dla Twojego urządzenia.
Sprawdź identyfikator transakcji.

Odpowiedź zawiera następujące zmienne w zależności od kodu odpowiedzi:

Zmienna
Format
Opis
Przykład
RC 200
RC 404
wynik
ciąg
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
PRZYJĘTO
TAK
NO
responseMessage
ciąg
Bardziej szczegółowy opis uzyskanej wartości.
“Odrzucone przez emitenta.”
TAK
NO
transanctionId
ciąg
Wewnętrzny identyfikator zadania
TAK
NO
transakcjaOperacja
ciąg
Możliwe wartości: "SALE", "VOID", "REFUND"
Operacja / rodzaj transakcji."
WYPRZEDAŻ
TAK
NO
transactionType
ciąg
Możliwe wartości: "CASH", "CARD"
KARTA
TAK
NO
merchantID
ciąg
Tylko w przypadku transakcji kartą – numer identyfikacyjny oddziału.
343382001
TAK
NO
porządek
ciąg
ID transakcji wygenerowane przez terminal
483591
TAK
NO
currencyCode
ciąg
Kod waluty (ISO 4217)
TAK
NO
kwota
liczba
Kwota transakcji z dokładnością do 2 miejsc po przecinku (400 CZK).
400
TAK
NO
TipAmount
liczba
Kwota napiwku podana z dokładnością do dwóch miejsc po przecinku (30 CZK).
3000
TAK
NO
maskedPan
ciąg
Ukryty numer karty.
XXXX XXXX XXXX 1233
TAK
NO
cardDataEntry
ciąg
Sposób odczytu karty – pasek magnetyczny, chip lub technologia zbliżeniowa
BEZKONTAKTOWY
TAK
NO
referenceNumber
ciąg
Numer referencyjny transakcji pobrany z wartości żądania zadania: originReferenceNum
FD123456
TAK
NO
numer pokwitowania
ciąg
Numer paragonu
12
TAK
NO
batchNumber
ciąg
Numer partii
2
TAK
NO
data
ciąg
Data i godzina autoryzacji transakcji
09.10.2021 15:34
TAK
NO
cardType
ciąg
Dane karty marki EMV pobrane z danych karty
Mastercard CL
TAK
NO
powód odrzucenia
ciąg
Powód odrzucenia transakcji
201
TAK
NO
authorizationCode
ciąg
Numer generowany po stronie GP
10293045
TAK
NO
sequenceNumber
ciąg
Numer generowany po stronie GP
102304128
TAK
NO
aid
ciąg
Identyfikuje aplikację EMV używaną do przetwarzania transakcji
40100000000
TAK
NO
pinMessage
boolean
Wskazuje, czy wprowadzono kod PIN
PIN_ENTERED lub NO_PIN
TAK
NO
cancelledBy
ciąg
W przypadku operacji anulowania wyświetli się tutaj contextID
TAK
NO
cardHolderVerificationMethod
ciąg
Tylko dla terminali Nexgo – oznacza sposób weryfikacji transakcji
PIN
TAK
NO
exceptionId
ciąg
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.
FujIk6
NO
TAK
typ
ciąg
Rodzaj wyjątku
VALIDATION_EXCEPTION
NO
TAK
wiadomość
ciąg
Raport o wyjątku
Hasło jest zbyt słabe
NO
TAK
kontekst
ciąg
Kontekst wyjątku – dodatkowe informacje.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
TAK
dccData
status (DCC)
ciąg
CZ: Podaje status DCC. Jeśli wyświetla się "ACCEPTED", oznacza to, że transakcja została zrealizowana za pośrednictwem DCC i należy wypełnić paragon DCC odpowiednimi danymi. Jeśli wyświetla się "NOT_ACCEPTED", w takim przypadku można zignorować dane DCC.
EN: Wskazuje status DCC. Jeśli wyświetla się komunikat "ACCEPTED", transakcja została zrealizowana za pośrednictwem DCC i należy wpisać dane DCC na paragonie. Jeśli wyświetla się komunikat "NOT_ACCEPTED", można zignorować dane DCC.
PRZYJĘTO
NOT_ACCEPTED
TAK
NO
kwota (DCC)
ciąg
CZ: Kwota transakcji w walucie DCC – w walucie karty klienta. Należy ją wyświetlić dokładnie tak, jak pojawi się w odpowiedzi API, łącznie z liczbą miejsc po przecinku.
EN: Kwota transakcji w walucie DCC – w walucie karty klienta. Należy ją podać na paragonie dokładnie tak, jak została otrzymana w odpowiedzi API, z zachowaniem prawidłowej liczby miejsc po przecinku.
2.31
TAK
NO
currencyCode (DCC)
ciąg
CZ: Waluta karty lojalnościowej.
EN: Waluta karty klienta.
EUR
TAK
NO
kurs wymiany (DCC)
ciąg
CZ: Podaje kurs wymiany. Wartość ta jest wyrażona w lokalnej walucie terminala. Należy ją wyświetlić dokładnie tak, jak pojawia się w odpowiedzi API, łącznie z liczbą miejsc po przecinku.
EN: Wskazuje kurs wymiany. Wartość ta jest podana w lokalnej walucie terminala. Należy ją podać na paragonie dokładnie tak, jak została otrzymana w odpowiedzi API, z zachowaniem prawidłowej liczby miejsc po przecinku.
56.35
TAK
NO
znaczniki (DCC)
ciąg
CZ: Dodatek do kursu wymiany. Należy go wyświetlić dokładnie tak, jak pojawia się w odpowiedzi API, łącznie z liczbą miejsc po przecinku.
EN: Oznaczenie współczynnika konwersji. Należy je podać na paragonie dokładnie tak, jak zostało otrzymane w odpowiedzi API, z zachowaniem prawidłowych miejsc po przecinku.
3.20
TAK
NO
regionSchemaIndicator (DCC)
ciąg
CZ: Wskazuje, czy karta klienta została wydana w UE, czy poza nią. Jeśli wartość wynosi "0" lub "1", na paragonie należy umieścić tekst "Markup". Jeśli wartość wynosi "2", na paragonie należy umieścić tekst "Markup over ECB rate".
EN: Wskazuje, czy karta klienta została wydana w UE, czy poza nią. Jeśli wartość wynosi "0" lub "1", na paragonie należy umieścić tekst "Markup". Jeśli wartość wynosi "2", na paragonie należy umieścić tekst "Markup powyżej kursu EBC”.
0
1
2
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.

Jak ci się podoba ten samouczek?
Wybierz walutę
CZK Korona czeska
€ Euro