Cloud POS

Quick Start Guide

Note: replace “mycompany” with your company name, and “term1” with the terminal
ID you are targeting.

Step 1: GET a session key

A session key locks the terminal to your software and ensures nobody else can
send a transaction to that device until you release the session.

(PROD) GET https://cloud.payments.ac/mycompany/terminals/term1/session
(SANDBOX) GEThttps://cloud-sandbox.payments.ac/mycompany/terminals/term1/session

Example: Creating a new session

$ curl

GET <https://cloud.payments.ac/mycompany/terminals/term1/session>

…
200 OK
{
	"terminalId": "123456",
	"sessionKey": “2eyCyPVOYnKU1u64UtckfpxldZIDLQD5”
	"sessionKeyExpiry": "2018-05-09 23:59:59"
}

Step 2: POST a transaction to the terminal

Post the transaction directly to the terminal. The terminal will pick up the
transaction and begin processing the transaction. You will need to provide the
session key obtained in Step 1 as an HTTP header.

Optional, but recommended: if you have the capability of receiving HTTP traffic
on your host, add a callbackUrl property to the transaction to receive a
callback when the transaction is processed.

Example:

$ curl
	-H "sessionKey: 2eyCyPVOYnKU1u64UtckfpxldZIDLQD5"
	POST https://cloud.payments.ac/mycompany/terminals/term1/transaction
	-D

>   {
>   "transactionType": "SALE",
>   "id": "123123",
>   "totalAmount": "10.00",
>   "currency": "USD",
>   "callbackUrl": "https://yourhostgoeshere.com/etc", // Optional
>   "configuration": {
>   "enableTip": "true",
>   },
>   }

…
201 CREATED
{
	"uuid": "b0c7e012-eb5c-4a21-8f32-5b8e2b16e863",
	"id": "123123",
	"transactionType": "SALE",
	"terminalId": "term1",
	"totalAmount": "10.00",
	"currency": "USD",
	"status": "QUEUED",
	"callbackUrl": "https://yourhostgoeshere.com/etc",
	"configuration": {
		"enableTip": "true",
	}
}

Step 3a – If you provided a callbackUrl

When the cloud terminal processes the transaction, the response will be POST’ed
back to the callback URL you provided in Step 2.

(callback from the terminal to callbackUrl) https://yourhostgoeshere.com/etc

{
	"uuid": "b0c7e012-eb5c-4a21-8f32-5b8e2b16e863",
	"id": "123123",
	"terminalId": "term1",
	"transactionType": "SALE",
	"approvedAmount": "10.00",
	"status": "APPROVED",
	"approvalCode": "ABC123",
	"responseText": "Transaction Approved",
	"cardType": "Visa",
	"cardNumber": "4012XXXXXXXX1881",
	"cardholderName": "John Doe",
	"currency": "USD",
}

Note: If you provided the sessionKey as a URL parameter to the callbackUrl in
step 2, you will get all the transaction data necessary to generate a receipt.
If you did not provide a sessionKey, you will get the transaction’s id, status,
and responseText fields. You will need to query the transaction directly to get
the fields necessary to generate a receipt.

Step 3b – If you did not provide a callbackUrl

You will need to poll for the result of the transaction. However, since the
transaction has been consumed by the terminal, it will no longer be in the
queue. You will need to query the transaction record directly to get the status.
Note the URL change below:

Example: Keep polling transaction with ID 123123 until the transaction
processes.

The ?poll parameter instructs the server to only return data if the transaction
has completed processing. This ensures the polling mechanism is lightweight and
keeps bandwidth to a minimum.

$ curl
\-H "sessionKey: 2eyCyPVOYnKU1u64UtckfpxldZIDLQD5"
GET https://cloud.payments.ac/mycompany/transactions/123123?poll
\-D
304 NOT MODIFIED

You will continue to get a 304 Not Modified response until the transaction
processes, in which case you will get a 200 OK plus the data necessary to
construct a receipt.

Note: To prevent server overload, please ensure the polling requests are three
seconds apart or greater.

$ curl

-H "sessionKey: 2eyCyPVOYnKU1u64UtckfpxldZIDLQD5"

GET https://cloud.payments.ac/mycompany/transactions/123123?poll

-D

200 OK

{

"uuid": "b0c7e012-eb5c-4a21-8f32-5b8e2b16e863",

"id": "123123",

"status": "APPROVED",

"responseText": "Transaction Approved",

}

$ curl

-H "sessionKey: 2eyCyPVOYnKU1u64UtckfpxldZIDLQD5"

GET https://cloud.payments.ac/mycompany/transactions/123123

-D

200 OK

{

"uuid": "b0c7e012-eb5c-4a21-8f32-5b8e2b16e863",

"id": "123123",

"terminalId": "term1",

"transactionType": "SALE",

"approvedAmount": "10.00",

"status": "APPROVED",

"approvalCode": "ABC123",

"responseText": "Transaction Approved",

"cardType": "Visa",

"cardNumber": "4012XXXXXXXX1881",

"cardholderName": "John Doe",

"currency": "USD",

}

Step 4 (Optional) – Close the session and release the device

It is recommended to close the session when done processing transactions.
However, you can elect to keep the session open as long as you wish, and send as
many transactions as you wish. Just be advised that nobody else will be able to
use that terminal while your session is open (this includes other browser
windows on your same computer).

Example: Delete the session when done

$ curl

-H "sessionKey: 2eyCyPVOYnKU1u64UtckfpxldZIDLQD5"

DELETE https://cloud.payments.ac/mycompany/terminals/term1/session

-D

204 NO CONTENT