Skip to content

Settlement

METHOD NAME settlement

Requires state IDLE and during process moves to SETTLEMENT

Description

Perform a settlement request to the host. Firstly, the terminal will update the parameters. Then, depending on the terminal configuration, it will pack the batch file and send all the transactions currently stored in the batch file. This settlement will have an id and batch number if any transaction is batched. This method returns once the request has been completed.

Parameters

object

  • host string REQUIRED
    Currently, the value is SHVA only

  • reportFormat ReportFormat
    The format for the report. Default NARROW
    (1) Show values

    1. ReportFormat

      The format of a report sent back from Shva.

      • NARROW Narrow paper printer
      • MEDIUM Medium sized paper printer
      • WIDE wide paper printer
      • XML XML format

    2. END

  • resetGen boolean
    Reset all parameters generation revision. Default false.

Result

object when a request is valid and settlement starts processing.

  • result Result
    Possible results are: OK, NETWORK_ERROR, GENERAL_ERROR
    (1) Show values

    1. Result

      Result of new request. Each command has possible values in the field.

      • OK Request is ok
      • GENERAL_ERROR An error occurred
      • CANCELED Command was canceled either by the user (on-screen) or through cancel command.
      • TIMEOUT Operation was timed out.
      • NETWORK_ERROR No internet connection is available.
      • HOST_ERROR Host returned an error regarding the request.
      • SMART_READER_ERROR An error occurred with the smart-reader
      • SMART_CARD_ERROR An error occurred with the smart card, or the reader couldn't communicate with the card.
      • NONE_CREDIT_CARD Industrial card was detected when performing a transaction.
      • CARD_NOT_ALLOWED When the detected card is not allowed to be processed

  • settlement Settlement
    Settlement payload

Important

Starting from version 1.4.5, the settlement object may be returned even when the result indicates a GENERAL_ERROR. The settlement process performs two independent tasks: updating terminal parameters and batching transactions (when working directly with the processor). Since transaction batching occurs in the middle of the parameters update process, a GENERAL_ERROR can occur in two scenarios:

  • Parameter update succeeds, batching fails: The settlement object will contain basic data only (no batching details)
  • Batching succeeds, parameter update fails: The settlement object will contain full batching data and report

Since batched transactions cannot be re-processed, the settlement object preserves transaction data when batching was successful, regardless of parameter update failures. Always check the settlement object content to determine which operations completed successfully.

Errors

  • HostDisabled
  • MissingParams
  • IllegalState
  • ScreenNotReady
  • InsufficientBattery

Example

Request

1
2
3
4
5
6
7
8
{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "method": "settlement",
  "params": {
        "host": "SHVA"    
    }
}

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "jsonrpc": "2.0",
  "id": "1234567890",
  "result": {
    "result": "OK",
    "settlement": {
        "terminalId": "0883198",
        "settlementId": "5b884a09-7d48-457a-91d6-fae615d6aeeb",
        "batchNo": "01649624",
        "report": " בדיקות ארנה          <!>מספר מסוף:  0884401   <!>תאריך:      27/11/2024<!>שעה:        19:34     <!>                      <!>מספר עסק ישראכרט      <!>   0071506            <!>מספר עסק כאל          <!>   0398021            <!>          MAX מספר עסק<!>   0300012            <!>AD30S30001     :PPCODE<!>......................",
        "settledTransactions": [
                {
                    "type": "R",
                    "referenceId": "5544a15f-2759-4622-8a97-53adfbbee184",
                    "transactionId": "24111020193508831988304"
                },
                {
                    "type": "R",
                    "referenceId": "65f0bf12-8a42-40d1-98aa-a91cb920cf1f",
                    "transactionId": "24111020204508831983607"
                }
        ],
        "time": "2024-11-28T01:34:00.264+08:00"
      }
    }
}