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
Typ bezpečnostního schématu / Security scheme
HTTP
Schéma autorizace HTTP / HTTP authorization scheme
bearer
Create a task
Call the POST /v1/tasks/TRANSACTION endpoint and use CreateCloudTaskTransactionApiRequest with the following information filled in to make the request:
Variable
Format
Description
Example
apiKey
MANDATORY
MANDATORY
String
API The key can be found directly in the app GP tom in the Account section-Cloud API . It is used to distinguish logins mainly in Cloud API . For each company, the API key is unique.
333W212J3
Tid
MANDATORY
MANDATORY
String
The target TID for the task. TID = Terminal ID, which is unique for each device. Only one TID can be used at a time on all installed devices.
483590
initiator
MANDATORY
MANDATORY
String
The initiator description should be unique to each instance of the subsystem that can initiate a task. Example: "Server XY" or "Cashier 1"
Cash desk 12
title
MANDATORY
MANDATORY
String
Human-readable task name. It should contain some identification of the task.
Example: "Invoice 37364FD"
Example: "Invoice 37364FD"
Invoice 36744
printByPaymentApp
Boolean
default: true
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.
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.
false
amount
MANDATORY
MANDATORY
number
The transaction amount must be non-zero and include decimal places. For a transaction value of 50 EUR, you fill in the value "5000".
40000
tipAmount
number
Amount of tipping. For a tip value of €3, fill in the value "300".
0
transactionOperation
MANDATORY
MANDATORY
String
The transaction type of the task. For the "Sale" transaction, fill in the "SALE" value.
SALE
originTransactionId
String
The ID of the transaction to cancel. Not null if VOID mode and cancel are OLDER_TRANSACTION.
NOT USED
originReferenceNum
String
Reference number, e.g. invoice number – add any value up to 20 characters that will be visible in the reports and identify the payment on your side.
FD123456
cancelMode
String
Reversal mode, not null if the transaction type is VOID
Possible values: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
Possible values: [ LAST_TRANSACTION, OLDER_TRANSACTION ]
NOT USED
transactionType*
MANDATORY
MANDATORY
String
Possible values: [ CASH, CARD, ACCOUNT_PAYMENT ]
CARD
currencyCode
String
3 currency characters (according to ISO 4217)
CZK
preferableReceiptType
String
Preselected method of sending the receipt: [ EMAIL, PHONE, QR, PRINT ]
EMAIL
email
String
Customer email
support@gptom.com
phone
String
Customer's phone number
+420123456789
TipCollect
Boolean
default: false
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.
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.
timeToLive
Integer
The expiration limit for the cloud job. You are allowed to specify values from 10 to 172800 seconds.
10
Content of the response [CloudTaskDetailApiResponse]:
Possible response codes are:
Response
Message
Description
How to behave
RC200
OK - Task has been registered
The task has been successfully created and will be processed.
Proceed to the next step in the transaction flow.
RC401
Unauthenticated
If the autenfitting with the terminal has not taken place.
Perform the authentication process (see step above).
RC403
The user is not allowed to register the task on the given terminal
If your API credentials do not match the TID value you sent (for example, if the TID owner is different).
Check that you have filled in the correct TID and try again.
RC406
the task is not acceptable for the terminal
This usually happens when the TID is unable to process the request.
Check the error message.
RC 502
Push notification not sent
The push notification was not sent due to an upstream service failure.
Below you will find the variables used in the response:
Variable
Format
Description
Example
RC200
RC403
RC406
RC502
title
String
Human-readable task name. Used from request value.
Invoice 36744
YES
WELL
WELL
WELL
taskId
String
Internal task id
dFd3sda
YES
WELL
WELL
WELL
created
String
The date and time the task was created.
YES
WELL
WELL
WELL
taskClass
String
Payload classPossible values: [TRANSACTION, BATCH, VOID]
TRANSACTION
YES
WELL
WELL
WELL
status
String
Cloud task status. Possible values: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
CREATED
YES
WELL
WELL
WELL
initiator
String
A description of the client-side initiator. Used from request value.
Cash desk 12
YES
WELL
WELL
WELL
contextId
String
The ID of the affected target entity, if any (transactionId / batchId)
YES
WELL
WELL
WELL
Payload
object
Context task body - depending on taskClass
{...}
YES
WELL
WELL
WELL
exceptionId
String
Pseudo-unique exception ID. It can serve as a "support ID" that the user can communicate to support so that they can investigate the error.
FujIk6
WELL
YES
YES
YES
type
String
Type of exception.
VALIDATION_EXCEPTION
WELL
YES
YES
YES
Message
String
Exception message.
Password too weak
WELL
YES
YES
YES
context
String
Exception context. Learn more.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
WELL
YES
YES
YES
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:
Variable
Format
Description
Example
taskId
String
The ID of the task that you received as part of the previous step.
dFd3sda
Possible return codes:
Response
Message
Message
Description
RC200
OK - Task status available
The job status update was successfully processed.
If you do not receive the final status (see below), repeat this step.
RC403
Cloud job not found for current terminal.
You should check your taskID and resubmit the correct value.
Check that you have filled in the correct taskID and try again.
Variables in the response:
Variable
Format
Description
Example
RC200
RC404
title
String
Human-readable task name. Used from the value of the task creation request.
Invoice 36744
YES
WELL
taskId
String
Internal task ID
dFd3sda
YES
WELL
created
String
The date and time the task was created.
YES
WELL
taskClass
String
Possible values: [TRANSACTION, BATCH, DUMMY]
YES
WELL
status
String
Possible values: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
IN_PROGRESS
YES
WELL
initiator
String
A description of the client-side initiator. Used from request value.
Cash desk 12
YES
WELL
contextID
String
The ID of the affected target entity, if any (transactionId / batchId)
YES
WELL
Payload
YES
WELL
exceptionId
String
Pseudo-unique exception ID. It can serve as a "support ID" that the user can communicate to support so that they can investigate any issue.
FujIk6
WELL
YES
type
String
Type of exception.
VALIDATION_EXCEPTION
WELL
YES
Message
String
Exception message.
Password too weak
WELL
YES
context
String
Exception context - more information.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
WELL
YES
The task status request should be repeated until you get one of the final response codes, which are:
Status
Description
How to behave
INIT_ERROR
The payment process failed to initialize. Check for the error you received.
Follow the error instructions.
COMPLETED
Once you get this status, your task has been completed and the result is available.
You can proceed to the next step.
CANCELLED
Task has been canceled by the user.
You should start a new job because this task has been canceled by the user.
ERROR
An error occurred while processing the job.
Follow the error instructions.
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é:
Variable
Format
Description
Example
contextId
String
The transaction ID that you get in the previous steps.
Possible response codes are:
Response
Message
Message
Description
RC200
OK – transaction details provided
Successful response to your request.
The transaction is completed!
RC404
A transaction could not be found for the current TID.
This condition occurs when a given transaction ID was not found for your device.
Check the transaction ID.
The response contains the following variables, depending on the response code:
Variable
Format
Description
Example
RC 200
RC 404
result
String
Transaction result, possible values [ ACCEPTED, DECLINED, CANCELLED ] where:
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
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
ACCEPTED
YES
WELL
responseMessage
String
A more detailed description of the resulting value.
"Refused by issuer."
YES
WELL
transanctionId
String
Internal Task ID
YES
WELL
transactionOperation
String
Possible rates: ""SALE"" "VOID"" "REFUND""
Operation/transaction type."
Operation/transaction type."
SALE
YES
WELL
transactionType
String
Possible values "CASH" "CARD"
CARD
YES
WELL
merchantID
String
Only for card transactions - branch ID.
343382001
YES
WELL
Tid
String
Transaction ID created by the terminal
483591
YES
WELL
currencyCode
String
Currency code (ISO 4217)
YES
WELL
amount
number
Transaction amount with 2 decimal places (400 CZK).
400
YES
WELL
tipAmount
number
The amount of the tip entered to 2 decimal places (30 CZK).
3000
YES
WELL
maskedPan
String
Masked card number.
XXXX XXXX XXXX 1233
YES
WELL
cardDataEntry
String
Method of card loading - magstripe, chip or contactless
CONTACTLESS
YES
WELL
referenceNumber
String
Transaction reference number taken from the task value of the request: originReferenceNum
FD123456
YES
WELL
receiptNumber
String
Receipt number
12
YES
WELL
batchNumber
String
Batch number
2
YES
WELL
date
String
Date and time of transaction authorization
09.10.2021 15:34
YES
WELL
cardType
String
EMV brand card taken from card data
Mastercard CL
YES
WELL
declinedReason
String
Reason for transaction rejection
201
YES
WELL
authorizationCode
String
Number generated on the GP side
10293045
YES
WELL
sequenceNumber
String
Number generated on the GP side
102304128
YES
WELL
aid
String
Identifies the EMV application used to process the transaction
40100000000
YES
WELL
pinMessage
Boolean
Indicates whether the input has occurred PIN
Ok
YES
WELL
cancelledBy
String
In case of a cancellation operation, the contextID will be displayed here
YES
WELL
cardHolderVerificationMethod
String
For Nexgo terminals only - indicates the transaction verification method
PIN
YES
WELL
exceptionId
String
Pseudo-unique exception ID. It can serve as a "support ID" that the user can communicate to support so that they can investigate.
FujIk6
WELL
YES
type
String
Exception type
VALIDATION_EXCEPTION
WELL
YES
Message
String
Exception message
Password too weak
WELL
YES
context
String
Exception context - more information.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
WELL
YES
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.