POS / Terminal Integration

Aurora provides a semi-integrated POS solution where your point-of-sale system sends transaction requests to the Aurora API, which routes them to a physical terminal for card processing. The terminal handles all card interaction (tap, insert, swipe) and communicates the result back through the API.

How It Works

1. Your POS system creates a transaction via the API, specifying the terminal and amount.
2. Aurora sends the transaction to the terminal via push notification.
3. The terminal prompts the customer to present their card.
4. The terminal processes the payment and reports the result.
5. Your POS system retrieves the result by polling the API.

Base URL

Sandbox Environment:

https://api.uat.arise.risewithaurora.com/pos-api/v1

Production Environment:

https://api.arise.risewithaurora.com/pos-api/v1

Terminals

Before processing transactions, you need to know which terminals are available.

List Terminals

GET /pos-api/v1/terminals

Returns a paginated list of terminals assigned to your merchant account.

Parameter	Type	Description
page	int	Page number.
pageSize	int	Items per page.
search	string	Search by terminal name or serial number.
serialNumber	string	Filter by serial number.

Each terminal in the response includes:

Field	Description
id	Terminal unique identifier. Use this when creating transactions.
serialNumber	The terminal's hardware serial number.
terminalManufacturer	Manufacturer name (e.g. Sunmi, Verifone).
terminalModel	Model name (e.g. P2, P3H, Victa Mobile).
terminalModeName	Operating mode (Standalone or SemiIntegrated).
connectionStatus	Current connection state (Online or Offline).

Get Terminal Status

GET /pos-api/v1/terminals/{terminalId}/status

Returns detailed real-time status for a specific terminal, including connectivity, battery level, and printer status.

Field	Description
terminalPosStatus	Active (ready to accept transactions) or Busy (currently processing).
connectionStatus	Online or Offline.
connectionType	WiFi, Mobile, or Ethernet.
batteryLevel	Battery percentage (0–100).
printerStatus	Normal, NotNormal, or NotSupported.
availabilityStatus	Ready or Busy.

tip

Check that a terminal is Online and Active before sending a transaction to avoid a TerminalOffline status.

Creating a Transaction

Start a POS Transaction

POST /pos-api/v1/pos-transactions

Field	Type	Required	Description
terminalId	string (UUID)	Yes	The terminal that will process the transaction.
transactionTypeId	int	Yes	Transaction type (see table below).
amount	decimal	Conditional	Amount in dollars. Required for Sale, Authorization, Capture, Refund, and Tip Adjustment.
posDeviceId	string	Yes	Your POS system's device identifier (max 36 characters).
referenceId	string	No	Your external reference ID for this transaction (max 36 characters).
targetTransactionId	string (UUID)	Conditional	The original transaction ID. Required for Void, Capture, and Refund.
customerId	string (UUID)	No	Associate the transaction with a stored customer.
readingMethodId	int	No	1 = Card read (tap/insert/swipe, default), 2 = Manual entry (keyed).
waitForAcceptanceByTerminal	bool	No	true = long poll until terminal accepts; false = return immediately (default).

Transaction Types

ID	Type	Description
1	Authorization	Place a hold on funds without capturing. Requires amount.
2	Sale	Authorize and capture in one step. Requires amount.
3	Capture	Capture a previous authorization. Requires amount and targetTransactionId.
4	Void	Cancel a transaction before settlement. Requires targetTransactionId.
5	Refund	Return funds from a settled transaction. Requires amount and targetTransactionId.
8	Tip Adjustment	Adjust the tip on an existing transaction. Requires amount and targetTransactionId.

Example — Sale transaction:

curl -X POST 'https://api.uat.arise.risewithaurora.com/pos-api/v1/pos-transactions' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "terminalId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
    "transactionTypeId": 2,
    "amount": 25.99,
    "posDeviceId": "POS-REGISTER-01",
    "referenceId": "ORDER-4521",
    "waitForAcceptanceByTerminal": false
  }'

Response:

{
  "posTransactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "statusId": 1,
  "status": "TerminalConnecting"
}

Get POS Transaction

GET /pos-api/v1/pos-transactions/{posTransactionId}

Parameter	Type	Description
posTransactionId	string (UUID)	Path parameter. The POS transaction ID returned from the create call.
waitForTransactionProcessing	bool	Query parameter. Set to true for long polling — the response holds until the transaction completes or times out.

When the transaction completes (isCompleted: true), the response includes full transaction details in the transaction object:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "posTransactionStatusId": 6,
  "posTransactionStatus": "Completed",
  "isCompleted": true,
  "amount": 25.99,
  "transaction": {
    "transactionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "amount": 25.99,
    "transactionStatus": "Captured",
    "authCode": "A12345"
  }
}

Polling for Results

After creating a transaction, poll the GET endpoint to track its progress.

Polling Strategies

Polling when creating a transaction:

• Short polling: Set waitForAcceptanceByTerminal: false when creating the POS transaction. Your POS controls the polling interval to retrieve the transaction status.
• Long polling: Set waitForAcceptanceByTerminal: true when creating the POS transaction. The response holds until the transaction is accepted by the terminal device or times out, reducing the number of API calls.

Polling to get the transaction results:

• Short polling: Poll GET with waitForTransactionProcessing: false when you want to check the transaction status at your own interval.
• Long polling: Poll GET with waitForTransactionProcessing: true to hold the request until the transaction reaches a final status, reducing the number of API calls.

Transaction Status Lifecycle

ID	Status	Final?	Description
1	TerminalConnecting	No	Transaction sent to the terminal. Waiting for the terminal to accept.
2	TransactionProcessing	No	Terminal accepted the transaction and is processing the card.
10	TransactionSentToProcessor	No	Card data submitted to the payment processor.
6	Completed	Yes	Transaction processed successfully.
3	DeclinedByProcessor	Yes	The payment processor declined the transaction.
4	CancelByPos	Yes	Your POS system cancelled the transaction.
5	CancelByTerminal	Yes	The transaction was cancelled at the terminal (e.g. customer pressed cancel).
9	TerminalOffline	Yes	The terminal could not be reached.
7	Error	Yes	A system error occurred during processing.
8	Inconsistency	Yes	A data mismatch occurred between the POS and terminal.

Check the isCompleted field to determine if the transaction has reached a final status.

Cancelling a Transaction

You can cancel a transaction that hasn't completed yet.

POST /pos-api/v1/pos-transactions/{posTransactionId}/cancel

Returns the updated transaction status. Cancellation is only possible while the transaction is in a non-final state (e.g. TerminalConnecting or TransactionProcessing).

Listing Transactions

GET /pos-api/v1/pos-transactions

Returns a paginated list of POS transactions. Supports filtering by terminal.

Parameter	Type	Description
page	int	Page number.
pageSize	int	Items per page.
terminalId	string (UUID)	Filter transactions by terminal.
asc	bool	Sort order. true = ascending, false = descending.
orderBy	string	Field name to sort by.

Printing a Receipt

Trigger a receipt reprint on a terminal for a completed transaction.

POST /pos-api/v1/pos-transactions/{posTransactionId}/print

{
  "terminalId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123"
}

Returns 200 OK with no body. The specified terminal will print the receipt.

Error Responses

All endpoints return standard HTTP error codes:

Status Code	Description
400 Bad Request	Invalid request — check that required fields are present and correctly formatted.
401 Unauthorized	Missing or invalid access token.
403 Forbidden	Your account does not have the required POS permission.
404 Not Found	The specified transaction or terminal was not found.
500 Internal Server Error	An unexpected error occurred. Contact support if the issue persists.