Sitoo Custom Payment SPI
Sitoo Custom Payment SPI is used to integrate an external Payment into Sitoo POS. The payment system will be called in real time directly from Sitoo POS and have control over the payment terminal UI to display QR-codes and status messages.
SPI (Service Provider Interface)
The SPI is the definition of the API required to use the service in Sitoo. Therefore, the external service needs to fully implement the API definition.
Real-time requests
Requests are made in real-time from Sitoo POS. It is important to have very low response times. Sitoo POS has an internal timeout of 10 seconds, but in general response times should never exceed 1 second.
Payment Flow
The flow is pretty straight forward. First a transaction is started from the POS using POST /payments. A paymentid is
returned. Then the POS enters a polling loop where it checks the paymentstate field on the payment
using GET /payments/{paymentid}. Depending on the state, the POS either updates the UI (inprogress), finishes with
failure (cancelled) or finishes with success (completed). If the state is ready_to_complete then the POS sets the state
completed, to acknowledge that the POS has accepted the payment, using PUT /payment/{paymentid}. Thus, it’s the POS
that sets the state to completed and never the payment system.
Notes
- When the Payment System has finished the payment it sets the paymentstate.state to "ready_to_complete" which indicates that the POS can set it to the "completed" state. This handshake mechanism ensures that the payment has been transferred to the POS and accepted.
- The POS must set the "completed" state within 3 minutes after the payment system sets it to "ready_to_complete". If the time is exceeded, the payment system should revert the transaction and set the state to "cancelled"
- If the payment system sets the state to "ready_to_complete" and the POS sets it to "cancelled" then the transaction should be reversed.
- If the state is completed and the POS sends a "cancelled", the transaction should be reverted if possible. Payment systems usually only allows this for the last transaction or within a certain time limit. The function is used if the staff want to cancel the payment in the POS.
Payment methods
- Sales. A regular sales transaction. An amount is paid by the customer using the payment system.
- Refund. The customer wants to make a refund. The amount in the transaction is negative and the amount should be paid to the customer.
- Reverse/Cancel. If the previous transaction needs to be cancelled, an update of the transaction state to "cancelled" is issued. A sales transaction should be reversed and the amount be paid back to the customer.
Receipts
Payments can have extra information that should be printed on the receipt. There are two possible entries on the receipt:
- One row directly below the payment row.
- An entire section. This allows for multiple lines. Rows can be printed in two different ways. Either just as a text or as two columns. If a tab character \x9 exists in the string, two column mode is selected. The title will be the first string before the first tab and the value everything after the first tab. The title has a limit of 12 characters.
