Settlement API

Introduction

The settlement API provide endpoints to create and manage settlements for both cash registers and store vaults. Settlements can be defined as sessions where money movements in and out are tracked for the vault and cash registers of a retail store.

For more details about this API usage check our API documentation

Preparation

  • Have an authenticated token from the authentication service, this token should be used as an authorization bearer token header for every request done in this API (more information about the authorization service here).

Create a vault settlement

One of the first things expected to be done when opening a new retail store is to create a vault settlement, this operation represents the cash money the store uses to start operations. A POST request to the /settlements endpoint needs to be done with the request body described bellow.

Example request body:

{
"type": "VAULT",
"initialCash": [{
"value":40000,
"currency":"EUR",
"method": "CASH"
}]
}

These are some important attributes to keep in mind when making the request:

  • The type value can either be VAULT or CASHREGISTER, in this example we are dealing with a VAULT settlement type.
  • initialCash contains a list of amounts of currencies the settlement will be opened with, for this example, only one amount of currency in cash is used.
  • The value value units are represented in cents (40000 represents 400,00€).

Example response:

{
"settlementId": "3a06a8e8-0b3d-4a4d-b969-8ab2c2e89b02",
"state": "OPEN",
"store": "1337",
"station": 0,
"openedByName": "Erika Mustermann",
"openedTime": 1541435925364,
"initialAmounts": [
{
"value": 40000,
"currency": "EUR",
"method": "CASH"
}
],
"apiResponseStatus": {
"responseCode": "I06001",
"message": "Settlement created successfully."
}
}

Here are some important observations in the response:

  • settlementId is an automatically generated UUID value.
  • state represents the current state of the settlement, OPEN state means the settlement is active and registering money movements in and out of the vault.
  • store represents store number identifier.
  • station represents the station identifier inside the store, vault settlements are always identified by 0 value.
  • openedTime is the timestamp when the settlement was opened, the value is expressed in milliseconds.

Create a cash register settlement

Only after a vault settlement is opened and active in a store is when cash register settlements can be created. In order to so, a POST request needs to be sent to the /settlements endpoint with the request body described bellow.

Example request body:

{
"type": "CASHREGISTER",
"initialCash": [{
"value":20000,
"currency":"EUR",
"method": "CASH"
}]
}

These are some important attributes to keep in mind when making the request:

  • The type of settlement we are dealing in this example is CASHREGISTER.
  • initialCash contains a list of amounts of currencies the settlement will be opened with, for this example, only one amount of currency in cash is used.
  • The value units are represented in cents (20000 represents 200,00€), this value represents the spare cash the cash register starts operations, typically at the start of every day.

Example response:

{
"settlementId": "3a06a8e8-0b3d-4a4d-b969-8ab2c2e89b02",
"state": "OPEN",
"store": "1337",
"station": 1,
"openedByName": "Erika Mustermann",
"openedTime": 1541435925364,
"initialAmounts": [
{
"value": 20000,
"currency": "EUR",
"method": "CASH"
}
],
"apiResponseStatus": {
"responseCode": "I06001",
"message": "Settlement created successfully."
}
}

Here are some important observations in the response:

  • settlement is an automatically generated UUID value.
  • state represents the current state of the settlement, OPEN state means the settlement is active and registering money movements in and out of the cash register. Only one settlement can be in OPEN state in any cash register.
  • store represents store number identifier.
  • station represents the station identifier inside the store there can many cash registers and this value is meant to differentiate one from another.
  • openedTime is the timestamp when the settlement was opened, the value is expressed in milliseconds.

Change a cash register settlement state to COUNTING

Cash register settlements can be changed to an intermediate COUNTING state where the application will calculate the total of all transactions made along the day plus the initial cash the settlement was opened with for all the different currencies and payment methods. In this state, the staff at the store is meant to manually count the cash in the cash drawer, so they can submit the amount counted in another API operation and make sure the amount counted in cash is the same calculated by the application. To change a settlement's state to COUNTING a PATCH request needs to be done to the /settlements/{settlementId} endpoint with the request body described bellow.

Example request body:

{
"state": "COUNTING"
}

Example response:

{
"settlementId": "3a06a8e8-0b3d-4a4d-b969-8ab2c2e89b02",
"state": "COUNTING",
"store": "1337",
"station": 1,
"openedByName": "Erika Mustermann",
"openedTime": 1541435925000,
"countedByName": "Erika Mustermann",
"countedTime": 1541435984374,
"initialAmounts": [
{
"value": 20000,
"currency": "EUR",
"method": "CASH"
}
],
"apiResponseStatus": {
"responseCode": "I06003",
"message": "Settlement updated successfully."
}
}

Here are some important observations in the response:

  • state represents the current state of the settlement, COUNTING state means the cash register settlement is no longer active and registering money movements in and out of the cash register, this is the previous state for closing the settlement.
  • countedTime is the timestamp when the settlement was set to COUNTING state, the value is expressed in milliseconds.

Preview a settlement

Cash register settlements in COUNTING state can be checked against the application to see if the cash total counted by the staff is the same as the cash total counted by the application (also known as preview operation). If the amount provided in the request matches the amount calculated by the application the settlement will be automatically changed to CLOSED state, if is not, the application will include in the response the amount of cash provided that did not match the one calculated by the application. If this operation is done three times without matching all the amounts provided, the settlement is automatically set to CLOSED state with the amounts provided in the last attempt. To perform this operation, a PATCH request needs to be done to the /settlements/{settlementId} endpoint with the request body described bellow.

Example request body:

{
"state": "COUNTING",
"amounts": [
{
"value":19000,
"currency":"EUR",
"method": "CASH"
}
]
}

These are some important attributes to keep in mind when making the request:

  • amounts contains a list of amounts of currencies counted in the cash drawer, in this example, only cash in
    euros was counted.

Example response:

{
"settlementId": "3a06a8e8-0b3d-4a4d-b969-8ab2c2e89b02",
"previewCount": 1,
"preview": [
{
"isEqual": false,
"currency": "EUR",
"method": "CASH"
}
],
"apiResponseStatus": {
"responseCode": "I06004",
"message": "Settlement previewed successfully."
}
}

Here are some important observations in the response:

  • previewCount the amount of times a settlement has been previewed, when it reaches to three attempts, the settlement is automatically changed to CLOSED state.
  • preview is a list of results from checking the amounts of cash in different currencies against the application, in this example the amount provided in the request didn't match the amount of cash calculated by the application, so the isEqual value is false, the two other attributes specify the payment method and currency.

Change a settlement state to CLOSED

A settlement in COUNTING state can also be directly changed to CLOSED state without performing a preview operation, the user should have in consideration the settlement will be closed with amounts provided in the request and major differences of cash calculated by the application could be yield as a result. To change a settlement to CLOSED state a PATCH request needs to be done to the /settlements/{settlementId} endpoint with the request body described bellow.

Example request body:

{
"state": "CLOSED",
"amounts": [
{
"value":21000,
"currency":"EUR",
"method": "CASH"
}
]
}

These are some important attributes to keep in mind when making the request:

  • state value tells us the desired state we want to change the settlement to.
  • amounts contains a list of amounts of currencies counted in the cash drawer, in this example, only cash in euros was counted, the settlement will be set to CLOSED state with this amount of cash counted.

Example response for cash register settlements:

{
"settlementId": "eaf77cde-98bc-42d8-977f-369a75b68f14",
"state": "CLOSED",
"store": "1337",
"station": 1,
"openedByName": "Erika Mustermann",
"openedTime": 1527087354441,
"countedByName": "Erika Mustermann",
"countedTime": 1527087366968,
"closedByName": "Erika Mustermann",
"closedTime" :1527087376970,
"targetAmounts": [
{
"value": 20000,
"currency": "EUR",
"method": "CASH"
}
],
"initialAmounts": [
{
"value": 20000,
"currency": "EUR",
"method": "CASH"
}
],
"actualAmounts": [
{
"value": 21000,
"currency": "EUR",
"method": "CASH"
}
],
"differenceAmounts": [
{
"value": 1000,
"currency": "EUR",
"method": "CASH"
}
],
"apiResponseStatus": {
"responseCode": "I06005",
"message": "Settlement closed successfully."
}
}

Here are some important observations in the response:

  • state represents the current state of the settlement, CLOSED state means the settlement no longer needs any interactions with the user and its data cannot be modified anymore. Is until this point that other settlements can be created in this same cash register.
  • targetAmounts contains a list of amounts of currencies calculated by the application, in this example, only cash in euros were calculated. This list is only given after the settlement is changed to CLOSED state.
  • actualAmounts contains a list of amounts of currencies counted in the cash drawer by the staff and was provided in the request body.
  • differenceAmounts contains a list of amounts with the difference between the target and actual amounts. This list is only given after the settlement is changed to CLOSED state.

Example response for vault settlements:

{
"settlementId": "eaf77cde-98bc-42d8-977f-369a75b68f14",
"state": "CLOSED",
"store": "1337",
"station": 0,
"openedByName": "Erika Mustermann",
"openedTime": 1527087354441,
"countedByName": "Erika Mustermann",
"countedTime": 1527087366968,
"closedByName": "Erika Mustermann",
"closedTime": 1527087376968,
"lastCountByName": "Erika Mustermann",
"lastCountTime": 1527082576968,
"targetAmounts": [
{
"value": 20000,
"currency": "EUR",
"method": "CASH"
}
],
"initialAmounts": [
{
"value": 20000,
"currency": "EUR",
"method": "CASH"
}
],
"actualAmounts": [
{
"value": 21000,
"currency": "EUR",
"method": "CASH"
}
],
"differenceAmounts": [
{
"value": 1000,
"currency": "EUR",
"method": "CASH"
}
],
"apiResponseStatus": {
"responseCode": "I06005",
"message": "Settlement closed successfully."
}
}

Here are some important observations about vault settlements:

  • As pointed out before, they can be differentiated from cash register settlement by the station value which is always 0.
  • They don't have the intermediate COUNTING state as cash register settlements have, they can only be changed from OPEN to CLOSED state. To change a vault settlement to CLOSED state, the same request for cash register settlements should be used.
  • They can be previewed as cash register settlements, with the only difference they can be previewed as many times the user needs, the settlement will be changed CLOSED state only when the specific request to do so is done.
  • Once a vault settlement is changed to CLOSED state, another one is created automatically in OPEN state with the actualAmounts list from the previous CLOSED settlement as initialAmounts, this means there will always be one vault settlement in OPEN state.
  • There can only be one and only one active (OPEN) vault settlement per store.

Query settlements

Settlements can be queried by making a GET request and providing a series of request parameters in the URL path, the request parameters can be any of the attributes of a settlement and can be combined based on user specific needs. In this example we are querying the settlements in OPEN state of store 1337, for this we construct the URL path with the following request parameters /settlements?store=1337&state=OPEN, no request body is required.

Example response:

{
"settlements":{
"content": [
{
"settlementId": "bfe22064-4ee3-4a51-8964-e10ee1ed6183",
"state": "OPEN",
"station": 0,
"openedByName": "Erika Mustermann",
"openedTime": 1527598933954,
"initialAmounts": [
{
"value": 20000,
"currency": "EUR",
"method": "CASH"
}
]
}
],
"last": true,
"totalPages": 1,
"totalElements": 1,
"size": 20,
"number": 0,
"sort": null,
"first": true,
"numberOfElements": 1
},
"apiResponseStatus": {
"responseCode": "I06006",
"message": "Settlements retrieved from query."
}
}

Here are some important observations in the response:

  • The response body is in a paginated structure with a default page size of 20 elements.
  • For the provided request parameters only one OPEN settlement was found for store 1337.