A sales transaction is a basic payment operation that provides for the transfer of a specified amount from the cardholder's bank account to the merchant's account.
As for the payment process, the procedure is as follows:
Login & Authentication
JWT token authentication is required for all non-public endpoints. You get the token (with a lifetime of 90 days) through the /cloud/oauth/token endpoint with the following arguments provided:
- Basic authentication for token endpoints (name/password) - will be provided for each user.
- Merchant username - same as for GP tom
- Merchant password - same as for GP tom
- Terminal ID (TID) – Destination terminal ID
- The authorization endpoint is located at:
This authentication method is the same for all terminals.
Get an access token
Example request:
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
Example answer:
{ "access_token": "eyJh…", // access token used in authenticated API requests "token_type": "bearer", "refresh_token": "GciO…", "expires_in": 3600, "scope": "read write", "tid": "999888", }
Token renewal
When the access_tokenu expires, refresh_token is available.
Example request:
POST {{apiHost}}/api/oauth/token
Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=GciO…
GPTomAuth
Create a task
Call the POST /v1/tasks/TRANSACTION endpoint and use CreateCloudTaskTransactionApiRequest with the following information filled in to make the request:
MANDATORY
MANDATORY
MANDATORY
MANDATORY
Example: "Invoice 37364FD"
True if the receipt is to be printed on the device.
Note: For mobile phones, you need to make sure that the Bluetooth printer is connected.
MANDATORY
MANDATORY
Possible values: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
MANDATORY
If set to true, the tip entry screen in GP tom will be called first.
To call this screen, you also need to have tipping enabled in the app.
Content of the response [CloudTaskDetailApiResponse]:
Possible response codes are:
Below you will find the variables used in the response:
Check the status of a task
V dalším kroku budete kontrolovat stav tasku na koncovém bodu GET /v1/tasks/{taskID} pomocí požadavku, který zahrnuje:
Possible return codes:
Variables in the response:
The task status request should be repeated until you get one of the final response codes, which are:
You can proceed to the next step only when the response is in the COMPLETED state.
Getting a payment result
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é:
Possible response codes are:
The response contains the following variables, depending on the response code:
ACCEPTED - the transaction was successfully authorized
DECLINED - the transaction was rejected for some reason
CANCELLED - if the transaction is cancelled by the operator or customer
Operation/transaction type."
If you are going to generate or print the receipt on your side, we recommend that you check which fields are required and must be printed/displayed on the receipt. The description is available here.