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
Creating a bag
Call the POST endpoint /v1/tasks/TRANSACTION and use CreateCloudTaskTransactionApiRequest with the following information filled in to create the request:
MANDATORY
MANDATORY
MANDATORY
MANDATORY
MANDATORY
MANDATORY
MANDATORY
Example: „Invoice 37364FD payment“
True if the receipt is to be printed on the device.
Note: For mobile phones, make sure the Bluetooth printer is connected.
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.
Content of the [CloudTaskDetailApiResponse]:
Possible answer codes are:
Below are the variables used in the response:
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:
Possible return codes:
Response variables:
The request for the state of the bag should be repeated until you get one of the final response codes, which are:
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:
Possible answer codes are:
The response contains the following variables depending on the response code:
ACCEPTED - the transaction has been successfully authorized
DECLINED - the transaction was rejected for some reason
CANCELLED - if the transaction is cancelled by the operator or the customer
Operation / transaction type."
If you will be generating or printing the receipt on your side, we recommend checking which fields are mandatory and must be printed/displayed on the receipt. A description is available here.