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 Genius mobile pay
- Trader password - same as for Genius mobile pay
- Terminal ID (TID) - ID of the destination terminal
- The authorization endpoint is located at:
Getting an access token
Content of the request:
curl –location ‚{{apiCloudHost}}/cloud/oauth/token‘ \ –header ‚Content-Type: application/x-www-form-urlencoded‘ \ –header ‚Authorisation: Basic YXRvbTphc2hmdWY0ZTVmYQ==‘ \ –data-urlencode ‚grant_type=password‘ \ –data-urlencode ‚password=ABCDEFGHIJKL‘ \ –data-urlencode ‚username=jan.novak@example.com‘ \ –data-urlencode ‚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 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
Operation / transaction type."
EN: Provides information on whether a voided transaction was processed as DCC
EN: If ACCEPTED, you must include the following text on your receipt:
The transaction amount, currency and exchange rate are the same as for the original transaction.
The currency conversion is provided by Global Payments.
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.