Introduction
Welcome to the Loomis PlatformSync API!
Our API comes in 2 flavors, Push API, and FTP File Delivery.
PlatformSync Push API
As its name implies, the Push API will push transactions into your endpoints provided by you. The transactions will be sent as soon as they are available and processed by our systems.
Transaction Delivery and Exceptions
Transactions flow from the safe into our system (the timing of this depends on a number of factors). In most cases, if we have connectivity to the safe and there is no issue with the quality of the data, then the transactions will flow through our system very quickly.
However, there are some exceptions that could impact delivery of transactions.
First, our system performs a series of checks to ensure that the transactions are genuine and trustworthy. If our system determines that there is a potential issue, then processing is halted until our staff can ensure data quality.
Second, we may have problems communicating with your service. In this case, we will attempt to redeliver the messages on an interval for 24 hours. See "Message Expiration" below for additional information.
Push API
The Push API will push certain types of transactions to your supplied endpoints. We will send the transactions as soon as they are available and processed by our system.
Setup
To begin the setup process, you must communicate directly with our support staff who will perform the requisite setup on our systems. Send an email to LoomisSafePointSupport@us.loomis.com to get started.
The following table represents the data that should be sent to Loomis to configure this service.
| Name | Required | More info |
|---|---|---|
| Endpoints | Yes | Your service endpoint that will accept the POST payload containing transactions. Multiple endpoints are supported. NOTE all data is sent to all the endpoints you provide. |
| Endpoint Type | No | Specifies type of environment (production, test, development, etc). This is an indicator for our staff to know what type of environment the endpoint is. |
| API Key(s) | Yes | Long-lived bearer token to authenticate with your service. Should be specified per Endpoint. |
| API Key Name | Yes | What key to use when sending the API key in the payload. Defaults to Authorization. |
| API Key Placement | Yes | Where to place the API Key/Value pair. Defaults to header. Can be one of header, body, query or metadata |
| Endpoint Metadata | No | Additional payload to send. Should be key-value pairs. Keys and values should be strings only. |
| Notification Recipients | No | Email addresses to send notifications to in the event of a failure. See "Failure Notifications" below for more information. |
| Transaction Whitelist | No | List of transactions that will be sent (See "Transaction Whitelist" below). |
| Max Batch Size | No | Maximum number of transactions to send at a time. Defaults to 1000. Maximum value is 1000. |
Endpoint URLs
You must provide a minimum of one public endpoint for your data to be sent to. The transactions will be sent as an HTTPS POST. Please note that a copy of all transactions will be sent to all the endpoints that you provide.
Also note that the endpoint must be accessible to the internet without any VPN connection.
Capacity Planning
There may be instances where we are POSTing a large volume of transactions at one time. Your service should be able to handle these bursts of high load. This can be mitigated by specifying a smaller batch size. However, this will result in more messages.
Loomis will work with you during the setup phase to provide an estimate of the expected load.
Security
Security should be implemented as a long-lived, unique API token. We do not support security via OAuth, certificates or username/password.
The token will be passed to your endpoint in the manner you specify (either in the body, query string, or header) with the property name you specify as well.
The provided endpoint(s) must be HTTPS only.
Transaction Whitelist
You may choose to receive any combination of the following types of transactions:
- ValidatedCashIn
- Cashin performed by the note validator on the safe
- Servicing
- A pickup by a Loomis courier
- ChangePurchase
- A request for an amount of change to be delivered and paid for out of the validated cash already dropped
- ManualCashTransaction
- A manual, non-validated drop
- CoinDispense
- Coins that were dispensed
- NoteDispense
- Notes that were dispensed
- TubeRemoved
- Tube removed from safe
- TubeLoaded
- Tube loaded into safe
- EndOfDay
- End of the accounting period on the safe
- BuyChange
- Recycler Notes and/or coin are deposited and an different denominations of equal total are dispensed
- CashAcceptedTillCheckin
- Recycler A register till is turned in to the recycler
- CashDispenseTillCheckout
- Recycler A register till is checked out of the recycler
- CashAcceptedAddCash
- Recycler Notes and/or coin entered into the recycler that are not associated with any specific transaction
- CashDispenseAdvanceCash
- Recycler Notes and/or coin dispensed from the recycler that are associated with a till that is checked out
- CashAcceptedReplenishment
- Recycler Notes and/or coin entered into the recycler from the external vault fund to increase inventory of the recycler
- CashAcceptedCashFundTransferIn
- Recycler Notes and/or coin entered into the recycler to log expense related transactions
- CashDispenseCashFundTransferOut
- Recycler Notes and/or coin entered dispensed from the recycler to log expense related transactions
- Logon
- User logged into the safe
- Logoff
- User logged out of the safe
- LockOpened
- Lock opened
- DoorOpened
- Door opened
- LockClosed
- Door closed
- DoorClosed
- Lock closed
- DoorWhine
- Alarm sounded due to a door left open past the timeout
- DoorWhineOverride
- Door open alarm manually overidden
Failure Notifications
We will attempt to deliver messages in a timely manner. If we are unable to reach your service, we will notify the email addresses provided by you of that failure, and will continue to attempt to deliver the messages.
Message Expiration
We will attempt to deliver your data on an interval for a period of 24 hours. If, after the 24-hours, we are still unable to deliver the transactions, we will send a second notification, and the messages will expire and not be retried.
Message Delivery Order
We will deliver the transactions ordered by date in which they occurred on the safe. We will make every attempt to deliver the transactions in the order in which they are processed by our system. However, occasionally, in the even of a failure, these messages may come in out of order. Your service should take this into account when accepting transactions.
FTP File Delivery
For additional details on setting up FTP delivery, please contact our team at LoomisSafePointSupport@us.loomis.com.
The full XML schema for the file can be requested.
Example XML Format
Transaction Object Properties
| Property Name | More Information |
|---|---|
| PickupGroupId | Groups transactions to a servicing |
| SerialNumber | Serial number of the safe that the transaction occurred on |
| RetrievedOn | Datetime of when the transaction was retrieved from the safe (ISO8601 UTC) |
| TransactionDateTime | Datetime of when the transaction occurred on the safe (In local time; will not include GMT offset) |
| UserName | Logged in user that performed the transaction |
| TransactionType | Type of transaction performed. Will be one of TransactionType's outlined below. |
| Amount | |
| DoorName | Name of the door and event associated with it. |
Transaction Types
- DoorOpened
- DoorClosed
- LockOpened
- LockClosed
- Login
- Logoff
Transactions
Payload
Transaction Object Properties
| Property Name | More Information |
|---|---|
| PickupGroupId | Groups transactions to a servicing |
| SerialNumber | Serial number of the safe that the transaction occurred on |
| RetrievedOn | Datetime of when the transaction was retrieved from the safe (ISO8601 UTC) |
| TransactionDateTime | Datetime of when the transaction occurred on the safe (In local time; will not include GMT offset) |
| UserName | Logged in user that performed the transaction |
| TransactionType | Type of transaction performed. Will be one of TransactionType's outlined below. |
| Amount | Total cash value of the transaction (if applicable). |
| Denominations | If the transaction was a validated drop or dispense, it will contain a list of bills or coin by denomination. For more information, see "Denomination Object" table below (if applicable). |
| Register | Which register, if any, that was used for the transaction (if properly configured on the safe). |
| ChangePurchaseNumber | Change purchase number, if any, that was used for the transaction (if properly configured on the safe). |
| DepositReferenceNumber | Deposit Reference Number, if any, that was used for the transaction (if properly configured on the safe). |
Transaction Types
- CashIn
- Servicing
- ChangeRequest
- ManualCashTransaction
- CoinDispenseBuyChange
- NoteDispenseBuyChange
- CoinDispense
- NoteDispense
- TubeRemoved
- TubeLoaded
- EndOfDay
- TubeDumped
- BuyChange
- CashAcceptedTillCheckin
- CashDispenseTillCheckout
- CashAcceptedAddCash
- CashDispenseAdvanceCash
- CashAcceptedReplenishment
- CashAcceptedCashFundTransferIn
- CashDispenseCashFundTransferOut
Denomination Object
| Property Name | More Information |
|---|---|
| UnitValue | Value of each bill or coin |
| Count | Number of bills or coin |
| Currency | Currency of the bill or coin |
Audit Transactions
Audit transactions are events that occur on the safe that don't directly have to do with cash being deposited into the safe.
Payload
Transaction Object Properties
| Property Name | More Information |
|---|---|
| PickupGroupId | Groups transactions to a servicing |
| SerialNumber | Serial number of the safe that the transaction occurred on |
| RetrievedOn | Datetime of when the transaction was retrieved from the safe (ISO8601 UTC) |
| TransactionDateTime | Datetime of when the transaction occurred on the safe (In local time; will not include GMT offset) |
| UserName | Logged in user that performed the transaction |
| TransactionType | Type of transaction performed. Will be one of TransactionType's outlined below. |
| Amount | |
| DoorName | Name of the door and event associated with it. |
Transaction Types
- Login
- Logoff
- LockOpened
- LockClosed
- DoorOpened
- DoorClosed
- DoorWhine
- DoorWhineOverride