Overview

Since Cloud terminals do not allow for follow-up transactions or the use of tokenized payment details, you can use this in conjunction with an existing transaction API (Payment API) to submit follow-up transactions (capture, void, refund) or use other gateway services that utilize payment information.

Choosing between Synchronous and Asynchronous Processing

Understanding the difference and choosing between the two available response styles will decide how you use the API, and whether or not you need to use the AsyncStatus Polling API.

• Synchronous: You issue your request and wait for a response from the gateway. Due to the customer interaction with the POI device, the wait time could be up to 5 minutes. You will receive a transaction ID and a final transaction condition in the response and do not need to do any follow-up AsyncStatus polling to determine the results of the transaction.
  • Why use it: This solution involves less development and the API response is identical to a standard Payment API response so if you already use the Payment API, parsing the response is simple.
  • Caveats: Due to internet connectivity issues, if you lose internet connectivity while waiting for the API call, you will not receive the API response. This will require you to query the gateway or log into the control panel to see the status of the transaction.
• Asynchronous: You issue your request and immediately get a GUID in return. You will then use the AsyncStatus Polling API to determine the state of the transaction and final condition once the customer’s interaction with the POI device is complete.
  • Why use it: This solution is ideal if your system needs to query on an in-flight transaction. In addition, asynchronous doesn’t require maintaining multiple sessions while a transaction processes, which is beneficial if you have many devices in the field. Responses are immediate for the Payment API and the AsyncStatus API.
  • Caveats: Due to the addition of the AsyncStatus API and, optionally, the Query API as a result of the limited transaction details in the response, this solution requires more development time and resources.

Steps to register a terminal and process a transaction

Step 1: Register your terminal using the current Code value visible on an internet-connected device.

Step 2: Process payments with your terminal using the returned POI Device ID.

• If you are using the synchronous method of processing, you will receive a transaction ID and the final condition of the transaction in the standard Payment API format.
• If you are using the asynchronous method of processing. see Step 3.

Step 3 (for Async users only): If you choose to process using the asynchronous method, you will have received a GUID in the response of Step 2. You will use this GUID to poll for the transaction and terminal status until the customer interaction has completed. The final results of the polling will return the final condition and transaction status.

Usage

Cloud terminals, referred to hereafter as "POI Device," must either be plugged into an ethernet port or connected to a WiFi network with internet access. Once the device has an internet connection, it will immediately try to connect to the platform and start rotating through registration codes.

Once your POI Device is registered, you can begin taking payments on it.

Authentication

Authentication is done via a "security key" that you can generate in your merchant control panel on the "Security Keys" Settings page. Select "API" for the key type.

This security key can be used with most other APIs (Payment, Three-Step, Query) except for Collect.js. You can use an existing API key that has the proper source selected (API.)

Testing credentials

If you have a staging terminal in hand, transactions can be tested using one of two methods:

• Transactions can be submitted to any merchant account that is in test mode. Keep in mind that if an account is in test mode, valid credit cards will be approved but no charges will actually be processed.
• If you do not wish to use (or do not have) your own account, the Payment Gateway demo account can also be used for testing transactions at any time. However, it does not support querying for security reasons. Please use the following security key for testing with this account: security_key = 2F822Rw39fx762MaV7Yy86jXGTC7sCDy