A sale transaction is a basic payment operation that transfers a specified amount from the cardholder's bank account to the merchant's account.
As far as the payment process is concerned, the procedure is as follows:
Login & Authentication
JWT token authentication is required for all non-public endpoints. The token (with a lifetime of 90 days) is obtained via the /cloud/oauth/token endpoint with the following arguments provided:
- Basic authentication for token endpoints (name/password) - will be provided for each user.
- Trader username - same as for GP tom
- Trader password - same as for GP tom
- Terminal ID (TID) - ID of the destination terminal
- The authorization endpoint is located at:
This authentication method is the same for all terminals.
Getting an access token
Example request:
POST {{apiCloudHost}}/cloud/oauth/token
Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
(Authorization and Contect-Type is always the same for all customers - please use the same data as in the example. You need to insert the unique client data into the grant_type afterwards).
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",
}Renewing a token
When the access_token expires, a 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
Scheme autorizace HTTP / HTTP authorization scheme
bearer
Creating a bag
Call the POST endpoint /v1/tasks/TRANSACTION and use CreateCloudTaskTransactionApiRequest with the following information filled in to create the request:
Variable
Format
Description
Example
apiKey
MANDATORY
MANDATORY
string
The API key can be found directly in the GP tom application in the Account-Cloud API section. It is used to distinguish logins mainly in the Cloud API. The API key is unique for each company.
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 for each subsystem instance that can initiate a task. Example: „Server XY“ or „Checkout 1“
Cash desk 12
title
MANDATORY
MANDATORY
string
A human-readable task title. It should include 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 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 the Bluetooth printer is connected.
false
amount
MANDATORY
MANDATORY
number
The transaction amount must be non-zero and include decimals. For a transaction value of EUR 50, enter „5000“.
40000
TipAmount
number
Amount of tip. For a tip value of EUR 3, enter „300“.
0
transactionOperation
MANDATORY
MANDATORY
string
Task transaction type. For the „Sale“ transaction, fill in the value „SALE“.
SALE
originTransactionId
string
Transaction ID to cancel. It is not null if the mode is VOID and the cancellation is OLDER_TRANSACTION.
NOT USED
originReferenceNum
string
Reference number, e.g. invoice number - add any value up to 20 characters that will be visible in reports and identifies the payment on your side.
FD123456
cancelMode
string
Cancellation 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, BLIK_PAYMENT, PAYMENT_GATEWAY ]
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 displayed first.
To display this screen, tips must also be enabled in the application
If set to true, the tip entry screen in GP tom will be displayed first.
To display this screen, tips must also be enabled in the application
timeToLive
Integer
The expiration limit for the cloud job. You are allowed to specify values from 10 to 172800 seconds.
10
Content of the [CloudTaskDetailApiResponse]:
Possible answer codes are:
Answer
Report
Description
How to behave
RC200
OK - Task has been registered
The task has been successfully created and will be processed.
Continue with 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 a job on the 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 occurs when the TID is unable to process the request.
Check the error message.
RC 502
Push notification not sent
Push notification was not sent due to upstream service failure.
Below are the variables used in the response:
Variable
Format
Description
Example
RC200
RC403
RC406
RC502
title
string
The human-readable name of the bag. Used from the request value.
Invoice 36744
YES
NO
NO
NO
taskId
string
Internal id of the bag
dFd3sda
YES
NO
NO
NO
created
string
The date and time the bag was created.
YES
NO
NO
NO
taskClass
string
Payload classPossible values: [TRANSACTION, BATCH, VOID]
TRANSACTION
YES
NO
NO
NO
status
string
Stav cloudového tasku. Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, COMPLETED, CANCELLED, ERROR]
CREATED
YES
NO
NO
NO
initiator
string
Client-side initiator description. Used from the request value.
Cash desk 12
YES
NO
NO
NO
contextId
string
ID of the affected target entity, if any (transactionId / batchId)
YES
NO
NO
NO
payload
object
Context task body - depending on the taskClass
{...}
YES
NO
NO
NO
exceptionId
string
Pseudo-unique exception ID. Can serve as a „support ID“ that the user can tell support to investigate the error.
FujIk6
NO
YES
YES
YES
type
string
Exception type.
VALIDATION_EXCEPTION
NO
YES
YES
YES
message
string
Exemption Report.
Password too weak
NO
YES
YES
YES
context
string
Context of the exception. Further information.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
YES
YES
Check the status of the bag
In the next step, you will check the status of the task on the GET /v1/tasks/{taskID} endpoint using a request that includes:
Variable
Format
Description
Example
taskId
string
The ID of the bag you received as part of the previous step.
dFd3sda
Possible return codes:
Answer
Report
Report
Description
RC200
OK - Bag status available
The task status update has been successfully processed.
If you do not receive the final status (see below), repeat this step.
RC403
A cloud job was not found for the current terminal.
You should check your taskID and resubmit the correct value.
Check that you have filled in the correct taskID and try again.
Response variables:
Variable
Format
Description
Example
RC200
RC404
title
string
A human-readable task title. Used from the task creation request value.
Invoice 36744
YES
NO
taskId
string
Internal bag ID
dFd3sda
YES
NO
created
string
The date and time the bag was created.
YES
NO
taskClass
string
Possible values: [TRANSACTION, BATCH, DUMMY]
YES
NO
status
string
Možné hodnoty: [CREATED, STARTED, INIT_OK, INIT_ERROR, COMPLETED, CANCELLED, ERROR]
COMPLETED
YES
NO
initiator
string
Client-side initiator description. Used from the request value.
Cash desk 12
YES
NO
contextID
string
ID of the affected target entity, if any (transactionId / batchId)
YES
NO
payload
YES
NO
exceptionId
string
Pseudo-unique exception ID. Can serve as a „support ID“ that the user can tell support to investigate a potential problem.
FujIk6
NO
YES
type
string
Exception type.
VALIDATION_EXCEPTION
NO
YES
message
string
Exception Report.
Password too weak
NO
YES
context
string
Exemption context - further information.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
The request for the state of the bag should be repeated until you get one of the final response codes, which are:
Status
Description
How to behave
INIT_ERROR
The initiation of the payment process failed. Check the error received.
Follow the instructions for the error.
COMPLETED
Once you get this status, your task has been completed and the result is available.
You can continue with the next step.
CANCELLED
The task has been cancelled by the user.
You should start a new task because this task has been cancelled by the user.
ERROR
An error occurred during the processing of the job.
Follow the instructions for the error.
You can only proceed to the next step if the answer is in the COMPLETED state.
Getting the payment result
We now know that the transaction has been authorized. The goal of this step is to get the transaction status and details of the transaction. For the new request, you will call the GET endpoint /v1/transactions/{transactionId} using the following variables:
Variable
Format
Description
Example
contextId
string
The transaction ID you obtained in the previous steps.
Possible answer codes are:
Answer
Report
Report
Description
RC200
OK - transaction details provided
Successful response to your request.
The transaction is complete!
RC404
No transaction was found for the current TID.
This condition occurs when the transaction ID has not been 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 authorised
DECLINED – the transaction was declined for some reason
CANCELLED – if the transaction is cancelled by a member of staff or a customer
ACCEPTED – the transaction was successfully authorised
DECLINED – the transaction was declined for some reason
CANCELLED – if the transaction is cancelled by a member of staff or a customer
ACCEPTED
YES
NO
responseMessage
string
A more detailed description of the resulting value.
“Refused by issuer.”
YES
NO
transanctionId
string
Internal task ID
YES
NO
transactionOperation
string
Possible values: ""SALE"" ""VOID"" ""REFUND""
Operation / transaction type."
Operation / transaction type."
SALE
YES
NO
transactionType
string
Possible values "CASH" "CARD"
CARD
YES
NO
merchantID
string
For card transactions only - Branch ID.
343382001
YES
NO
tid
string
ID of the transaction created by the terminal
483591
YES
NO
currencyCode
string
Currency code (ISO 4217)
YES
NO
amount
number
Transaction amount with 2 decimal places (400 CZK).
400
YES
NO
TipAmount
number
Tip amount entered to 2 decimal places (30 CZK).
3000
YES
NO
maskedPan
string
Masked card number.
XXXX XXXX XXXX 1233
YES
NO
cardDataEntry
string
Method of card loading - magstripe, chip or contactless
CONTACTLESS
YES
NO
referenceNumber
string
Transaction reference number taken from the request task value: originReferenceNum
FD123456
YES
NO
receiptNumber
string
Receipt number
12
YES
NO
batchNumber
string
Batch number
2
YES
NO
date
string
Date and time of transaction authorization
09.10.2021 15:34
YES
NO
cardType
string
EMV brand of the card taken from the card data
Mastercard CL
YES
NO
declinedReason
string
Reason for transaction rejection
201
YES
NO
authorizationCode
string
Number generated on GP side
10293045
YES
NO
sequenceNumber
string
Number generated on GP side
102304128
YES
NO
aid
string
Identifies the EMV application used to process the transaction
40100000000
YES
NO
pinMessage
boolean
Indicates whether a PIN has been entered
PIN_ENTERED or NO_PIN
YES
NO
cancelledBy
string
In case of a cancellation operation, the contextID will be displayed here
YES
NO
cardHolderVerificationMethod
string
For Nexgo terminals only - indicates the transaction verification method
PIN
YES
NO
exceptionId
string
Pseudo-unique exception ID. Can serve as a „support ID“ that the user can tell support to investigate.
FujIk6
NO
YES
type
string
Exception type
VALIDATION_EXCEPTION
NO
YES
message
string
Exception report
Password too weak
NO
YES
context
string
Exemption context - further information.
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
NO
YES
dccData
status (DCC)
string
CZ: Indicates the status of the DCC. If "ACCEPTED", the transaction was made via DCC and you must populate the receipt with DCC data. If "NOT_ACCEPTED", then you can ignore the DCC data.
EN: Indicates the DCC status. If "ACCEPTED", the transaction was made via DCC and you must fill in the receipt with DCC data. If "NOT_ACCEPTED", then you can ignore the DCC data.
EN: Indicates the DCC status. If "ACCEPTED", the transaction was made via DCC and you must fill in the receipt with DCC data. If "NOT_ACCEPTED", then you can ignore the DCC data.
ACCEPTED
NOT_ACCEPTED
NOT_ACCEPTED
YES
NO
amount (DCC)
string
EN: Transaction amount in DCC currency – in the customer’s card currency. It must be displayed exactly as it appears in the API response, including the number of decimal places.
EN: Transaction amount in DCC currency – in the currency of the customer’s card. You must display this on your receipt exactly as received via the API response, including the correct decimal places.
EN: Transaction amount in DCC currency – in the currency of the customer’s card. You must display this on your receipt exactly as received via the API response, including the correct decimal places.
2.31
YES
NO
currencyCode (DCC)
string
CZ: Customer card currency.
EN: Currency of the customer's card.
EN: Currency of the customer's card.
EUR
YES
NO
exchangeRate (DCC)
string
EN: Specifies the exchange rate. This value is in the terminal’s local currency. It must be displayed exactly as it appears in the API response, including the number of decimal places.
EN: Indicates the exchange rate. This value is in the local terminal currency. You must display it on your receipt exactly as received in the API response, including the correct decimal places.
EN: Indicates the exchange rate. This value is in the local terminal currency. You must display it on your receipt exactly as received in the API response, including the correct decimal places.
56.35
YES
NO
markup (DCC)
string
CZ: Conversion rate surcharge. It must be displayed exactly as it appears in the API response, including the number of decimal places.
EN: Markup for the conversion rate. You must display it on your receipt exactly as received in the API response, including the correct decimal places.
EN: Markup for the conversion rate. You must display it on your receipt exactly as received in the API response, including the correct decimal places.
3.20
YES
NO
regionSchemaIndicator (DCC)
string
CZ: Indicates whether the customer’s card was issued within the EU or outside it. If the value is "0" or "1", the text "Markup" must be displayed on the receipt. If the value is "2", the text "Markup over ECB rate" must be displayed on the receipt.
EN: Indicates whether the customer's card was issued within the EU or outside. If the value is "0" or "1", the text "Markup" must be displayed on the receipt. If the value is "2", the text "Markup over ECB rate" must be displayed on the receipt.
EN: Indicates whether the customer's card was issued within the EU or outside. If the value is "0" or "1", the text "Markup" must be displayed on the receipt. If the value is "2", the text "Markup over ECB rate" must be displayed on the receipt.
0
1
2
1
2
YES
NO
If you are generating or printing the receipt yourself, we recommend that you check which fields are mandatory and must be printed/displayed on the receipt. A description is available here.