Information
If you make a cancellation call through the Cloud API, you must create a task for the device (TID) where the payment was originally made. Calling a payment cancellation made on terminal „A“ on terminal „B“ is not currently supported.
A cancellation transaction is a basic payment operation that allows you to cancel a previously processed transaction up to 93 days from the original transaction. Cancellation of a transaction can be done without a customer card - funds will be automatically returned to the card used for the original sale transaction.
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:
Getting an access token
Example request:
POST {{apiCloudHost}}/cloud/oauth/token
Authorization: Basic YXRvbTphc2hmdWY0ZTVmYQ==
Content-Type: application/x-www-form-urlencoded
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
Type of security scheme
HTTP Authorization Scheme
HTTP
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
apiKey
MANDATORY
MANDATORY
tid
MANDATORY
MANDATORY
initiator
MANDATORY
MANDATORY
title
MANDATORY
MANDATORY
printByPaymentApp
amount
MANDATORY
MANDATORY
TipAmount
transactionOperation
originTransactionId
originReferenceNum
cancelMode
MANDATORY
MANDATORY
transactionType*
MANDATORY
MANDATORY
currencyCode
timeToLive
Format
string
string
string
string
boolean
number
number
string
string
string
string
string
string
Integer
Description
The API key can be found directly in the application in the Account-Cloud API section. It is used to distinguish logins mainly in the Cloud API.
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.
The initiator description should be unique for each subsystem instance that can initiate a task. Example: „Server XY“ or „Checkout 1“
A human-readable task title. It should include some identification of the task.
Example: „Invoice 37364FD payment“
Example: „Invoice 37364FD payment“
default value: true
True if the receipt is to be printed on the device.
Note: For mobile phones, make sure the Bluetooth printer is connected.
True if the receipt is to be printed on the device.
Note: For mobile phones, make sure the Bluetooth printer is connected.
The amount of the transaction to be cancelled must be non-zero and include decimals.
It is not used for cancellation.
Transaction type of the bag. For the „Cancellation Transaction“ transaction, fill in the „VOID“ value.
Transaction ID to cancel. It is not null if the mode is VOID and the cancellation is OLDER_TRANSACTION.
If you do not want to print this value on the receipt, leave blank.
Possible values: [ LAST_TRANSACTION, OLDER_TRANSACTION ] where:
LAST_TRANSACTION - used only for a previously authorized transaction. There can be no other request between this task and the previous sales task.
OLDER_TRANSACTION - used for all older transactions except the last transaction.
LAST_TRANSACTION - used only for a previously authorized transaction. There can be no other request between this task and the previous sales task.
OLDER_TRANSACTION - used for all older transactions except the last transaction.
Possible values: [ CASH, CARD ]
3 characters for currency code (ISO 4217)
The expiration limit for the cloud job. You are allowed to specify values from the interval seconds.
Example
333W212J3
483590
Cash desk 12
Cancellation 36744
false
40000
NOT USED
VOID
FD283737333
OPTIONAL
OLDER_TRANSACTION
CARD
CZK
10
Content of the [CloudTaskDetailApiResponse]:
Possible answer codes are:
Answer
RC200
RC403
RC406
RC 502
Report
OK - Task has been registered
The user is not allowed to register a job on the terminal
The task is not acceptable for the terminal
Push notification not sent
Description
The task has been successfully created and will be processed.
If your API credentials do not match the TID value you sent (for example, if the TID owner is different).
This usually occurs when the TID is unable to process the request.
Push notification was not sent due to upstream service failure.
How to behave
Continue with the next step in the transaction flow.
Check that you have filled in the correct TID and try again.
Check the error message.
Below are the variables used in the response:
Variable
title
taskId
created
taskClass
status
initiator
contextId
payload
exceptionId
type
message
context
Format
string
string
string
string
string
string
string
object
string
string
string
string
Description
The human-readable name of the bag. Used from the request value.
Internal id of the bag
The date and time the bag was created.
Payload classPossible values: [TRANSACTION, BATCH, DUMMY]
Cloud bag status. Possible values: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Client-side initiator description. Used from the request value.
ID of the affected target entity, if any (transactionId / batchId)
Context task body - depending on the taskClass
Pseudo-unique exception ID. Can serve as a „support ID“ that the user can tell support to investigate the error.
Exception type.
Exemption Report.
Context of the exception. Further information.
Example
Invoice 36744
dFd3sda
TRANSACTION
CREATED
Cash desk 12
{...}
FujIk6
VALIDATION_EXCEPTION
Password too weak
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
YES
YES
YES
YES
YES
YES
YES
YES
NO
NO
NO
NO
RC403
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
YES
RC406
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
YES
RC502
NO
NO
NO
NO
NO
NO
NO
NO
YES
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
taskId
Format
string
Description
The ID of the bag you received as part of the previous step.
Example
dFd3sda
Possible return codes:
Answer
RC200
RC403
Report
OK - Bag status available
A cloud job was not found for the current terminal.
Report
The task status update has been successfully processed.
You should check your taskID and resubmit the correct value.
Description
If you do not receive the final status (see below), repeat this step.
Check that you have filled in the correct taskID and try again.
Response variables:
Variable
title
taskId
created
taskClass
status
initiator
contextID
payload
exceptionId
type
message
context
Format
string
string
string
string
string
string
string
string
string
string
string
Description
A human-readable task title. Used from the task creation request value.
Internal bag ID
The date and time the bag was created.
Possible values: [TRANSACTION, BATCH, DUMMY]
Possible values: [CREATED, STARTED, INIT_OK, INIT_ERROR, IN_PROGRESS, COMPLETED, CANCELLED, ERROR]
Client-side initiator description. Used from the request value.
ID of the affected target entity, if any (transactionId / batchId)
Pseudo-unique exception ID. Can serve as a „support ID“ that the user can tell support to investigate a potential problem.
Exception type.
Exception Report.
Exemption context - further information.
Example
Invoice 36744
dFd3sda
IN_PROGRESS
Cash desk 12
FujIk6
VALIDATION_EXCEPTION
Password too weak
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
RC200
YES
YES
YES
YES
YES
YES
YES
YES
NO
NO
NO
NO
RC404
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
YES
The request for the state of the bag should be repeated until you get one of the final response codes, which are:
Status
INIT_ERROR
COMPLETED
CANCELLED
ERROR
Description
The initiation of the payment process failed. Check the error received.
Once you get this status, your task has been completed and the result is available.
The task has been cancelled by the user.
An error occurred during the processing of the job.
How to behave
Follow the instructions for the error.
You can continue with the next step.
You should start a new task because this task has been cancelled by the user.
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
transactionId
Format
string
Description
The transaction ID you obtained in the previous steps.
Example
4414c640-2db7-11ec-910a-91880dadec20
Possible answer codes are:
Answer
RC200
RC404
Report
OK - transaction details provided
No transaction was found for the current TID.
Report
Successful response to your request.
This condition occurs when the transaction ID has not been found for your device.
Description
The transaction is complete!
Check the transaction ID.
The response contains the following variables depending on the response code:
Variable
result
responseMessage
transanctionId
transactionOperation
transactionType
merchantID
tid
currencyCode
amount
TipAmount
cardNumber
cardDataEntry
referenceNumber
invoiceNumber
date
emvAppLabel
sequenceNumber
exceptionId
type
message
context
dccData": {"status"}
Format
string
string
string
string
string
string
string
string
number
number
string
string
string
string
string
string
string
string
string
string
string
string
Description
Výsledek transakce, možné hodnoty [ ACCEPTED, DECLINED, CANCELLED ] kde:
ACCEPTED - transakce byla úspěšně autorizována
DECLINED - transakce byla zamítnuta z nějakého důvodu
CANCELLED - pokud je transakce zrušena obsluhou nebo zákazníkem
ACCEPTED - transakce byla úspěšně autorizována
DECLINED - transakce byla zamítnuta z nějakého důvodu
CANCELLED - pokud je transakce zrušena obsluhou nebo zákazníkem
A more detailed description of the resulting value.
Internal task ID
Possible values: ""SALE"" ""VOID"" ""REFUND""
Operation / transaction type."
Operation / transaction type."
Possible values "CASH" "CARD"
For card transactions only - Branch ID.
ID of the transaction created by the terminal
Currency code (ISO 4217)
Transaction amount with 2 decimal places (400 CZK).
Tip amount entered to 2 decimal places (30 CZK).
Masked card number.
Method of card loading - magstripe, chip or contactless.
Transaction reference number taken from the request task value: originReferenceNum
Date and time of transaction authorization
EMV brand of the card taken from the card data
Number generated on GP side
Pseudo-unique exception ID. Can serve as a „support ID“ that the user can tell support to investigate.
Exception type
Exception report
Exemption context - further information.
CZ: Udává informaci, zda se stornuje DCC transakce
EN: Gives iformation whether voided transaction was processed as DCC
EN: Gives iformation whether voided transaction was processed as DCC
Example
ACCEPTED
null
4414c640-2db7-11ec-910a-91880dadec20
VOID
CARD
343382001
483591
40000
-
1233
null
FD123456
2020-09-16T09:31:16.000Z
null
102304128
FujIk6
VALIDATION_EXCEPTION
Password too weak
[INSUFFICIENT_DIGIT]:{minimumRequired=1, matchingCharacterCount=0, validCharacters=0123456789, matchingCharacters=}
CZ: Pokud ACCEPTED, je potřeba na účtenku dát text:
EN: If ACCEPTED, you need to put on your receit following text:
The transaction amount, currency and the exchange rate are the same as for the original transaction.
The currency conversion is provided by Global Payments.
EN: If ACCEPTED, you need to put on your receit following text:
The transaction amount, currency and the exchange rate are the same as for the original transaction.
The currency conversion is provided by Global Payments.
RC 200
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
NO
NO
NO
NO
YES
RC 404
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
YES
YES
YES
YES
NO
Pokud budete účtenku generovat nebo tisknout na své straně, doporučujeme zkontrolovat, která pole jsou povinná a musí být vytištěna/zobrazena na účtence. Popis je k dispozici zde.