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
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:
Ta metoda uwierzytelniania jest taka sama dla wszystkich terminali.
Uzyskiwanie tokenu dostępu
Przykładowe żądanie:
POST {{apiCloudHost}}/cloud/oauth/token
Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
(Authorization a Contect-Type je pro všechny zákazníky vždy stejný – použijte prosím stejné údaje jako v příkladu. Do grant_type je potřeba následně vložit unikátní údaje klienta).
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 bezpečnostního schématu / Security scheme
HTTP
Schéma autorizace HTTP / HTTP authorization scheme
bearer
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
Format
Opis
Przykład
apiKey
OBOWIĄZKOWE
OBOWIĄZKOWE
ciąg
Klucz API można znaleźć bezpośrednio w aplikacji GP tom w sekcji Account-Cloud API. Służy on do rozróżniania loginów głównie w Cloud API. Klucz API jest unikalny dla każdej firmy.
333W212J3
tid
OBOWIĄZKI
OBOWIĄZKI
ciąg
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.
483590
inicjator
OBOWIĄZKI
OBOWIĄZKI
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 12
tytuł
OBOWIĄZKOWE
OBOWIĄZKOWE
ciąg
Czytelny dla człowieka tytuł zadania. Powinien zawierać pewną identyfikację zadania.
Przykład: "Faktura 37364FD".
Przykład: "Faktura 37364FD".
Faktura 36744
printByPaymentApp
logiczna
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.
fałszywy
kwota
OBOWIĄZKOWE
OBOWIĄZKOWE
liczba
Kwota transakcji musi być niezerowa i zawierać ułamki dziesiętne. W przypadku transakcji o wartości 50 EUR należy wpisać "5000".
40000
TipAmount
liczba
Kwota napiwku. W przypadku napiwku o wartości 3 EUR należy wpisać "300".
0
transactionOperation
OBOWIĄZKOWE
OBOWIĄZKOWE
ciąg
Typ transakcji zadania. Dla transakcji "Sprzedaż" wpisz wartość "SPRZEDAŻ".
SPRZEDAŻ
originTransactionId
ciąg
Identyfikator transakcji do anulowania. Nie ma wartości null, jeśli tryb to VOID, a anulowanie to OLDER_TRANSACTION.
NIEUŻYWANY
originReferenceNum
ciąg
Numer referencyjny, np. numer faktury - dodaj dowolną wartość do 20 znaków, która będzie widoczna w raportach i identyfikuje płatność po Twojej stronie.
FD123456
cancelMode
ciąg
Tryb anulowania, nie null, jeśli typ transakcji to VOID
Możliwe wartości: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
Możliwe wartości: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
NIEUŻYWANY
transactionType*
OBOWIĄZKOWE
OBOWIĄZKOWE
ciąg
Możliwe wartości: [ CASH, CARD, ACCOUNT_PAYMENT ]
KARTA
currencyCode
ciąg
3 znaki waluty (zgodnie z normą ISO 4217)
CZK
preferableReceiptType
ciąg
Wstępnie wybrana metoda wysyłania paragonu: [ EMAIL, PHONE, QR, PRINT ].
EMAIL
e-mail
ciąg
E-mail klienta
support@gptom.com
telefon
ciąg
Numer telefonu klienta
+420123456789
TipCollect
logiczna
default: false
Jeśli ustawione na true, ekran wprowadzania napiwków w GP tom będzie wywoływany jako pierwszy.
Aby wywołać ten ekran, musisz mieć również włączone napiwki w aplikacji.
Jeśli ustawione na true, ekran wprowadzania napiwków w GP tom będzie wywoływany jako pierwszy.
Aby wywołać ten ekran, musisz mieć również włączone napiwki w aplikacji.
timeToLive (czas na życie)
liczba całkowita
Limit wygaśnięcia zadania w chmurze. Można określić wartości 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 przetworzone.
Przejdź do następnego kroku w przepływie transakcji.
RC401
Nieuwierzytelniony
Jeśli automatyczna konfiguracja z terminalem nie została przeprowadzona.
Przeprowadź proces uwierzytelniania (patrz krok powyżej).
RC403
Użytkownik nie może zarejestrować zadania na terminalu
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).
Sprawdź, czy wpisałeś prawidłowy identyfikator TID i spróbuj ponownie.
RC406
Zadanie nie jest akceptowalne dla terminala
Zwykle 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 upstream.
Poniżej znajdują się zmienne użyte w odpowiedzi:
Zmienna
Format
Opis
Przykład
RC200
RC403
RC406
RC502
tytuł
ciąg
Czytelna dla człowieka nazwa worka. Używana z wartości żądania.
Faktura 36744
TAK
NIE
NIE
NIE
taskId
ciąg
Wewnętrzny identyfikator torby
dFd3sda
TAK
NIE
NIE
NIE
stworzony
ciąg
Data i godzina utworzenia torby.
TAK
NIE
NIE
NIE
taskClass
ciąg
Klasa ładunkuMożliwe wartości: [TRANSACTION, BATCH, VOID]
TRANSAKCJA
TAK
NIE
NIE
NIE
status
ciąg
Status torby w chmurze. Możliwe wartości: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR].
UTWORZONY
TAK
NIE
NIE
NIE
inicjator
ciąg
Opis inicjatora po stronie klienta. Używany z wartości żądania.
Kasa 12
TAK
NIE
NIE
NIE
contextId
ciąg
Identyfikator podmiotu docelowego, którego dotyczy transakcja, jeśli dotyczy (transactionId / batchId)
TAK
NIE
NIE
NIE
ładunek
obiekt
Treść zadania kontekstowego - w zależności od taskClass
{...}
TAK
NIE
NIE
NIE
exceptionId
ciąg
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.
FujIk6
NIE
TAK
TAK
TAK
typ
ciąg
Typ wyjątku.
VALIDATION_EXCEPTION
NIE
TAK
TAK
TAK
wiadomość
ciąg
Raport o zwolnieniu.
Zbyt słabe hasło
NIE
TAK
TAK
TAK
kontekst
ciąg
Kontekst wyjątku. Dalsze informacje.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NIE
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
Format
Opis
Przykład
taskId
ciąg
Identyfikator torby otrzymanej w poprzednim kroku.
dFd3sda
Możliwe kody zwrotne:
Odpowiedź
Raport
Raport
Opis
RC200
OK - status torby dostępny
Aktualizacja statusu zadania została pomyślnie przetworzona.
Jeśli nie otrzymasz statusu końcowego (patrz poniżej), powtórz ten krok.
RC403
Nie znaleziono zadania w chmurze dla bieżącego terminala.
Powinieneś sprawdzić swój taskID i ponownie przesłać poprawną wartość.
Sprawdź, czy wpisałeś prawidłowy identyfikator zadania i spróbuj ponownie.
Zmienne odpowiedzi:
Zmienna
Format
Opis
Przykład
RC200
RC404
tytuł
ciąg
Czytelny dla człowieka tytuł zadania. Używany z wartości żądania utworzenia zadania.
Faktura 36744
TAK
NIE
taskId
ciąg
Wewnętrzny identyfikator torby
dFd3sda
TAK
NIE
stworzony
ciąg
Data i godzina utworzenia torby.
TAK
NIE
taskClass
ciąg
Możliwe wartości: [TRANSACTION, BATCH, DUMMY]
TAK
NIE
status
ciąg
Możliwe wartości: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR].
IN_PROGRESS
TAK
NIE
inicjator
ciąg
Opis inicjatora po stronie klienta. Używany z wartości żądania.
Kasa 12
TAK
NIE
contextID
ciąg
Identyfikator podmiotu docelowego, którego dotyczy transakcja, jeśli dotyczy (transactionId / batchId)
TAK
NIE
ładunek
TAK
NIE
exceptionId
ciąg
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.
FujIk6
NIE
TAK
typ
ciąg
Typ wyjątku.
VALIDATION_EXCEPTION
NIE
TAK
wiadomość
ciąg
Raport o wyjątkach.
Zbyt słabe hasło
NIE
TAK
kontekst
ciąg
Kontekst zwolnienia - dalsze informacje.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NIE
TAK
Zapytanie o stan torby należy powtarzać aż do 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 następnego kroku.
ODWOŁANE
Zadanie zostało anulowane przez użytkownika.
Należy 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ż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
Format
Opis
Przykład
contextId
ciąg
Identyfikator transakcji uzyskany w poprzednich krokach.
Możliwe kody odpowiedzi to:
Odpowiedź
Raport
Raport
Opis
RC200
OK - podano szczegóły transakcji
Pomyślna odpowiedź na żądanie.
Transakcja została zakończona!
RC404
Nie znaleziono transakcji dla bieżącego identyfikatora TID.
Ten stan występuje, gdy identyfikator transakcji nie został znaleziony dla 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 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
PRZYJĘTY
TAK
NIE
responseMessage
ciąg
Bardziej szczegółowy opis wartości wynikowej.
"Odrzucony przez wystawcę".
TAK
NIE
transanctionId
ciąg
Wewnętrzny identyfikator zadania
TAK
NIE
transactionOperation
ciąg
Możliwe wartości: ""SALE"" ""VOID"" ""REFUND""
Typ operacji / transakcji".
Typ operacji / transakcji".
SPRZEDAŻ
TAK
NIE
transactionType
ciąg
Możliwe wartości "GOTÓWKA" "KARTA"
KARTA
TAK
NIE
merchantID
ciąg
Tylko dla transakcji kartą - ID oddziału.
343382001
TAK
NIE
porządek
ciąg
Identyfikator transakcji utworzonej przez terminal
483591
TAK
NIE
currencyCode
ciąg
Kod waluty (ISO 4217)
TAK
NIE
kwota
liczba
Kwota transakcji z 2 miejscami po przecinku (400 CZK).
400
TAK
NIE
TipAmount
liczba
Kwota napiwku wprowadzona z dokładnością do 2 miejsc po przecinku (30 CZK).
3000
TAK
NIE
maskedPan
ciąg
Zamaskowany numer karty.
XXXX XXXX XXXX 1233
TAK
NIE
cardDataEntry
ciąg
Metoda ładowania karty - magstripe, chip lub zbliżeniowa
BEZKONTAKTOWY
TAK
NIE
referenceNumber
ciąg
Numer referencyjny transakcji pobrany z wartości zadania żądania: originReferenceNum
FD123456
TAK
NIE
receiptNumber
ciąg
Numer pokwitowania
12
TAK
NIE
batchNumber
ciąg
Numer partii
2
TAK
NIE
data
ciąg
Data i godzina autoryzacji transakcji
09.10.2021 15:34
TAK
NIE
cardType
ciąg
Marka EMV karty pobrana z danych karty
Mastercard CL
TAK
NIE
declinedReason
ciąg
Powód odrzucenia transakcji
201
TAK
NIE
authorizationCode
ciąg
Numer wygenerowany po stronie GP
10293045
TAK
NIE
sequenceNumber
ciąg
Numer wygenerowany po stronie GP
102304128
TAK
NIE
pomoc
ciąg
Identyfikuje aplikację EMV używaną do przetwarzania transakcji.
40100000000
TAK
NIE
pinMessage
logiczna
Wskazuje, czy wprowadzono kod PIN
Ok
TAK
NIE
cancelledBy
ciąg
W przypadku operacji anulowania, identyfikator contextID zostanie wyświetlony tutaj
TAK
NIE
cardHolderVerificationMethod
ciąg
Tylko dla terminali Nexgo - wskazuje metodę weryfikacji transakcji.
PIN
TAK
NIE
exceptionId
ciąg
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.
FujIk6
NIE
TAK
typ
ciąg
Typ wyjątku
VALIDATION_EXCEPTION
NIE
TAK
wiadomość
ciąg
Raport o wyjątkach
Zbyt słabe hasło
NIE
TAK
kontekst
ciąg
Kontekst zwolnienia - dalsze informacje.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NIE
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.