Skip to content

Start Transaction

METHOD NAME startTransaction

Requires state IDLE and moves to TRANSACTION during processing. If stopped through flow control, the state moves to WAITING_FOR_CONTINUE upon a non-completed response. Once completed, move to IDLE.

This method is Cancelable in certain states.

  • While waiting for a card
  • while waiting for any user input
  • while waiting for the continueTransaction command

The payment device waits for the continueTransaction command for 60 seconds before timing out. If the command is not received within this period, the transaction will be canceled.

Description

This method starts a payment transaction. Payment requests contain several unconditional steps, such as waiting for a card, entering a PIN, obtaining online authorization, displaying a tip screen, and entering MoTo. Each one of the steps manages its timeout according to terminal configuration. The method startTransaction will return once the transaction has been completed successfully (approved) or with another result (e.g., timeout).

If an error occurs during the request process, the result will be error.

Alternatively, the client can control this method's return point using flow control in the parameters object.

Parameters

object

  • paymentMethod PaymentMethod REQUIRED
    Payment method for this transaction. Only CREDIT_CARD is supported.

  • transactionType TransactionType REQUIRED
    The type of transaction to request the funds or operation to perform on an already existing transaction request.
    (1) Show values

    1. TransactionType

      Describe the type of transaction. Some of the values are used as input only and affect only the TransactionStatus

      • SALE Sale transaction.
      • REFUND Refund Transaction.
      • AUTH_ONLY Authorization only for a SALE transaction. Upon CAPTURE, this type becomes a SALE transaction.
      • CASH - TBD
      • CASHBACK - Cashback transaction.
      • VOID - Void transaction. This transaction type acts as an operation on an already existing transaction. The registered type is not changed; upon success, only the transaction status is set to VOIDED.
      • CAPTURE - Capture an AUTH_ONLY transaction. This transaction type acts as an operation to an already AUTH_ONLY existing transaction. Upon success, the registered type is changed to SALE and the status to CAPTURED.
      • FORCED - Forced transaction
      • TOP_UP - Top-Up transaction for prepaid cards
      • DISCHARGE - Discharge all funds on prepaid card
      • BALANCE - Balance inquiry request. This transaction is not registered or cached on the device.

  • referenceId string REQUIRED
    A unique string that identifies the transaction on the client side. The client generates this value. When requesting to VOID or CAPTURE a transaction, the value must be equal to the original transaction referenceId as provided. Each transaction request must have a new id with all other transaction types.
    Min Length 1, Max Length 64, Allowed characters are azAZ09_-

  • amount long
    The amount of money to authorize this transaction, not including tipAmount. The amount must be specified in the smallest denomination of the applicable currency. See Monetary Amount
    REQUIRED for transactionType of SALE, REFUND, AUTH_ONLY, CASHBACK, FORCED, TOP_UP, DISCHARGE

  • currency int
    The currency code of all amount fields that relate to the transaction. The currency must be specified as an ISO numeric code. See Monetary Amount
    REQUIRED when amount is specified.

  • cashAmount long
    The amount of money that is cashed back to the cardholder. The amount must be specified in the smallest denomination of the applicable currency. See Monetary Amount
    REQUIRED for transactionType of CASHBACK.

  • paymentType PaymentType
    The type of the payment source. This field is used for MoTo/Card-Non-Present. Upon requesting any of the MoTo types, card details will be prompted on the device for maximum security.
    Default is CARD_PRESENT.
    (1) Show values

    1. PaymentType

      Type of source for card data.

      • CARD_PRESENT The card is present during the transaction and used to read the card details using one of the acceptable methods.
      • MOTO The card is not present during the transaction; it is delivered by mail or telephone and typed manually into the POS.
      • SIGNATURE The card is present during the transaction but typed manually into the POS.

    Flow Control

  • notifyUpdate boolean
    Send a response regarding this transaction request when a card is read. If set to true, a response with UPDATE status will be received in the response, and another call to Continue Transaction will be needed to complete the transaction.
    default false

  • notifyReferral boolean
    Respond to this transaction request when the transaction is referred to as voice authorization. If set to true, a response with REFERRAL status will be received in the response, and another call to Continue Transaction will be needed to complete the transaction.
    default false

  • notifyEvents boolean
    Send transaction progress events during the processing. All events are received through the notification Transaction Events
    default false

    Credit Terms

  • creditTerms CreditTerms
    The credit terms are to be used for this transaction. This can't be set during VOID or CAPTURE
    Default is REGULAR.
    (1) Show values

    1. CreditTerms

      Transaction Credit terms. Only for Israel Credit Card transaction

      • REGULAR Regular credit terms
      • SPECIAL Special Credit terms (Isracredit/ Adif30)
      • IMMEDIATE Immediate credit
      • CREDIT Credit transaction. The amount is equaled evenly by the Card issuer after the sale.
      • INSTALLMENTS Installments transaction. The amount is divided by the merchant during the sale.

  • noOtherInstallmentPayments int
    The number of additional payments when using the INSTALLMENTS credit term. This number doesn't include the first payment. For example, for a Transaction of a total of 4 payments in installment terms, this value is equal to 3.
    REQUIRED for creditTerms of INSTALLMENTS.

  • firstPayment long
    The amount of money to charge on the first payment on the INSTALLMENTS transaction. The amount must be specified in the smallest denomination of the applicable currency. See Monetary Amount
    OPTIONAL for creditTerms of INSTALLMENTS. If not provided, the transaction is divided into noOtherInstallmentPayments + 1 equal payments where the modulus of the division is added to firstPayment.

  • noCreditPayments int
    The number of credit payments when using the CREDIT credit term. This number represents the total number of credit payments. The card issuer divides.
    REQUIRED for creditTerms of CREDIT.

  • paymentLinkedTo PaymentLinked
    The credit terms linking use for this transaction.
    OPTIONAL for creditTerms of CREDIT or INSTALLMENTS. Default is NONE.
    (1) Show values

    1. PaymentLinked

      Link Credit / Installment payment

      • NONE None
      • INDEX To Index AKA צמוד מדד
      • FOREIGN_CURRENCY to Foreign currency

    More Options

  • authorizationNumber string
    An optional number acquired from the card issuer over telephony authorization
    Min Length 1, Max Length 7

  • forceAuthorization boolean
    Force an online authorization for this transaction. If the device is not connected to the internet, the transaction will be declined offline
    default false

  • deferMonth int
    Defer transaction in N months
    Values are between 1 to 12

  • dueDate string
    Acquire funds on a date
    Length 6 in format yyMMdd

  • authorizationHost AuthorizationHost
    Overrides the device-level routing for the authorization phase of this transaction only.
    Default is DEFAULT (uses the device configuration, see directAuthToHost in Config).
    (1) Show values

    1. AuthorizationHost

      Defines the routing target for the authorization phase of a transaction.

      • DEFAULT Use the device configuration (see directAuthToHost in Config).
      • DIRECT Send authorization directly to the host (SHVA). Deposit and settlement remain unaffected.
      • GATEWAY Send authorization through the configured paymentGateway, even if the device is configured for direct authorization to host.

    Associated Data

  • shiftId string
    An optional field to associate with this transaction
    Min Length 1, Max Length 64, Allowed characters are azAZ09_-

  • dealId string
    An optional field to associate with this transaction
    Min Length 1, Max Length 64, Allowed characters are azAZ09_-

  • addendum string
    An optional field that can be included with the transaction to send additional information to the processor or gateway.
    This field follows the ANS format and supports all ANSI characters.

    Tip

  • tipAmount long
    The amount of money is designated as a tip. This amount is added to amount, and the summary of the two will be the totalAmount the cardholder will be charged. The amount must be specified in the smallest denomination of the applicable currency. See Monetary Amount

  • tipScreen boolean
    Request a tip from the cardholder. The selected tipAmount will be returned in the response. This field comes in conjunction with tipAmount in the request. The selected tip on the Tip Screen will override any tipAmount input

Result

object after the transaction starts processing and the request is valid

  • result Result
    Possible results are: OK, GENERAL_ERROR, CANCELED, TIMEOUT, HOST_ERROR, SMART_READER_ERROR, SMART_CARD_ERROR, NONE_CREDIT_CARD
    (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

  • commandStatus CommandStatus
    The status of the transaction during the response
    (1) Show values

    1. CommandStatus

      Describe the status of the transaction request that started with startTransaction or continued with continueTransaction

      • UPDATE Transaction is in an update state, and a call to continueTransaction is required to complete it. This state indicates that there were no errors, the card was read, and the final transaction terms can be modified.
      • REFERRAL Transaction is in a referral state, requiring a call to continueTransaction to complete the transaction. This state indicates no errors and requires voice authorization to complete the transaction.
      • COMPLETED Transaction request has been completed, and the client is not required to take further action.

  • transaction Transaction
    Transaction payload

Callbacks

Errors

  • MissingParams one of the REQUIRED parameters, is missing.
  • InvalidParams

  • IllegalRequest

    Reason Description
    AMOUNT_LIMIT_EXCEEDED when amount exceeds the configured amount limit

  • IllegalState

  • ScreenNotReady
  • PaymentMethodDisabled
  • HostNotReady
  • TransactionAlreadyExist
  • TransactionNotFound
  • IllegalTransactionStatus
  • InsufficientBattery

See Errors

Example

Basic Sale Transaction

Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "jsonrpc": "2.0",
    "method": "startTransaction",
    "id": "1234567890",
    "params": {
        "paymentMethod": "CREDIT_CARD",
        "transactionType": "SALE",
        "referenceId": "abcdef123456",
        "amount": 1000,
        "currency": 376
    }
}

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
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
{
    "jsonrpc": "2.0",
    "id": "1234567890",
    "result": {
        "result": "OK",
        "commandStatus": "COMPLETED",
        "transaction": {
            "transactionStatus": "CAPTURED",
            "transactionTime": "2024-11-20T17:55:32.968+08:00",
            "referenceId": "abcdef123456",
            "terminalId": "0881198",
            "appVersion": "1.0.0-rc.7",
            "transactionType": "SALE",
            "amount": 1000,
            "totalAmount": 1000,
            "tipAmount": 0,
            "currency": 376,
            "transactionId": "24112017553208811987387",
            "authorizationNumber": "0792200",
            "rrn": "957179218   ",
            "systemTraceNumber": "01001001",
            "cardName": "ויזה רגיל",
            "maskedPan": "458008XXXXXX3303",
            "panSuffix": "3303",
            "terminalNo": 1,
            "creditTerms": "REGULAR",
            "panEntryMode": "EMV",
            "acquirer": 7,
            "acquirerName": "קארדקום",
            "acquirerBusinessNumber": "0010124",
            "acquirerPhoneNumber": "039999999",
            "issuer": 2,
            "issuerName": "כאל",
            "brand": 2,
            "brandName": "ויזה",
            "isClub": false,
            "isPrepaid": false,
            "cvvResponse": 0,
            "cardHolderIdResponse": 0,
            "cardHolderReceipt": {
                "fields": [
                    {
                        "id": "POS_NAME",
                        "key": "שם מסוף",
                        "value": "TESTדנגוט טסט"
                    },
                    {
                        "id": "POS_NUM",
                        "key": "מס מסוף",
                        "value": "0881198"
                    },
                    {
                        "id": "SOFTWARE_VERSION",
                        "key": "גרסת תוכנה",
                        "value": "100000"
                    },
                    {
                        "id": "MERCHANT_ID",
                        "key": "מס עסק",
                        "value": "0010124"
                    },
                    {
                        "id": "POS_TRAN_ID",
                        "key": "מס שובר",
                        "value": "01001001"
                    },
                    {
                        "id": "UID",
                        "key": "UID",
                        "value": "24112017553208811987387"
                    },
                    {
                        "id": "RRN",
                        "key": "RRN",
                        "value": "957179218"
                    },
                    {
                        "id": "TRAN_TYPE",
                        "key": "סוג עסקה",
                        "value": "חובה"
                    },
                    {
                        "id": "ISSUER_AUTH_NUM",
                        "key": "מס אישור",
                        "value": "0792200"
                    },
                    {
                        "id": "AUTH_BY",
                        "key": "גורם מאשר",
                        "value": "חברה"
                    },
                    {
                        "id": "ENTRY_MODE",
                        "key": "אופן ביצוע",
                        "value": "כרטיס חכם"
                    },
                    {
                        "id": "CREDIT_TERMS",
                        "key": "סוג אשראי",
                        "value": "רגיל"
                    },
                    {
                        "id": "CARD_NAME",
                        "key": "כרטיס",
                        "value": "ויזה רגיל"
                    },
                    {
                        "id": "CARD_NUMBER",
                        "key": "מס כרטיס",
                        "value": "XXXXXXXXXXXX3303"
                    },
                    {
                        "id": "AMOUNT",
                        "key": "סכום",
                        "value": "10.00   ש\"ח"
                    },
                    {
                        "id": "TRAN_DATE_TIME",
                        "key": "תאריך ושעה",
                        "value": "17:55 20/11/24"
                    },
                    {
                        "id": "AID",
                        "key": "AID",
                        "value": "A0000000031010"
                    },
                    {
                        "id": "ATC",
                        "key": "סידורי ש",
                        "value": "0034"
                    },
                    {
                        "id": "PSN",
                        "key": "סידורי כ",
                        "value": "01"
                    },
                    {
                        "id": "TSI",
                        "key": "TSI",
                        "value": "E800"
                    },
                    {
                        "id": "ARC",
                        "key": "ARC",
                        "value": "00"
                    },
                    {
                        "id": "TVR",
                        "key": "TVR",
                        "value": "0080001000"
                    },
                    {
                        "id": "VERIFIED_BY_PIN",
                        "key": "Verified by PIN"
                    }
                ],
                "language": "HEBREW"
            },
            "merchantReceipt": {
                "collectSignature": false,
                "collectTelephoneNo": false,
                "fields": [
                    {
                        "id": "POS_NAME",
                        "key": "שם מסוף",
                        "value": "TESTדנגוט טסט"
                    },
                    {
                        "id": "POS_NUM",
                        "key": "מס מסוף",
                        "value": "0881198"
                    },
                    {
                        "id": "SOFTWARE_VERSION",
                        "key": "גרסת תוכנה",
                        "value": "100000"
                    },
                    {
                        "id": "MERCHANT_ID",
                        "key": "מס עסק",
                        "value": "0010124"
                    },
                    {
                        "id": "POS_TRAN_ID",
                        "key": "מס שובר",
                        "value": "01001001"
                    },
                    {
                        "id": "UID",
                        "key": "UID",
                        "value": "24112017553208811987387"
                    },
                    {
                        "id": "RRN",
                        "key": "RRN",
                        "value": "957179218"
                    },
                    {
                        "id": "TRAN_TYPE",
                        "key": "סוג עסקה",
                        "value": "חובה"
                    },
                    {
                        "id": "ISSUER_AUTH_NUM",
                        "key": "מס אישור",
                        "value": "0792200"
                    },
                    {
                        "id": "AUTH_BY",
                        "key": "גורם מאשר",
                        "value": "חברה"
                    },
                    {
                        "id": "ENTRY_MODE",
                        "key": "אופן ביצוע",
                        "value": "כרטיס חכם"
                    },
                    {
                        "id": "CREDIT_TERMS",
                        "key": "סוג אשראי",
                        "value": "רגיל"
                    },
                    {
                        "id": "CARD_NAME",
                        "key": "כרטיס",
                        "value": "ויזה רגיל"
                    },
                    {
                        "id": "CARD_NUMBER",
                        "key": "מס כרטיס",
                        "value": "458008XXXXXX3303"
                    },
                    {
                        "id": "AMOUNT",
                        "key": "סכום",
                        "value": "10.00   ש\"ח"
                    },
                    {
                        "id": "TRAN_DATE_TIME",
                        "key": "תאריך ושעה",
                        "value": "17:55 20/11/24"
                    },
                    {
                        "id": "AID",
                        "key": "AID",
                        "value": "A0000000031010"
                    },
                    {
                        "id": "ATC",
                        "key": "סידורי ש",
                        "value": "0034"
                    },
                    {
                        "id": "PSN",
                        "key": "סידורי כ",
                        "value": "01"
                    },
                    {
                        "id": "TSI",
                        "key": "TSI",
                        "value": "E800"
                    },
                    {
                        "id": "ARC",
                        "key": "ARC",
                        "value": "00"
                    },
                    {
                        "id": "TVR",
                        "key": "TVR",
                        "value": "0080001000"
                    },
                    {
                        "id": "VERIFIED_BY_PIN",
                        "key": "Verified by PIN"
                    }
                ],
                "language": "HEBREW"
            }
        }
    }
}

Sale Transaction with Update on card details

Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{`
    "jsonrpc": "2.0",
    "method": "startTransaction",
    "id": "1234567890",
    "params": {
        "paymentMethod": "CREDIT_CARD",
        "transactionType": "SALE",
        "referenceId": "abcdef123456",
        "amount": 1000,
        "currency": 376,
        "notifyUpdate": true
    }
}

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
    "jsonrpc": "2.0",
    "id": "1234567890",
    "result": {
        "result": "OK",
        "commandStatus": "UPDATE",
        "transaction": {
            "transactionTime": "2024-11-20T18:17:02.44+08:00",
            "referenceId": "abcdef123456",
            "terminalId": "0881198",
            "appVersion": "1.0.0-rc.7",
            "transactionType": "SALE",
            "amount": 1000,
            "totalAmount": 1000,
            "tipAmount": 0,
            "currency": 376,
            "transactionId": "24112018170208811986255",
            "systemTraceNumber": "01001002",
            "maskedPan": "458008XXXXXX3303",
            "panSuffix": "3303",
            "terminalNo": 1,
            "allowedCreditTerms": [
                "REGULAR",
                "SPECIAL",
                "CREDIT",
                "INSTALLMENTS"
            ],
            "maxNumberInstallmentPayments": 12,
            "maxNumberCreditPayments": 18,
            "minNumberCreditPayments": 3,
            "minAmountPerCreditPayments": 2500,
            "cvvRequired": false,
            "cardHolderIdRequired": false,
            "creditTerms": "REGULAR",
            "panEntryMode": "EMV",
            "acquirer": 7,
            "acquirerName": "קארדקום",
            "acquirerBusinessNumber": "0010124",
            "acquirerPhoneNumber": "039999999",
            "issuer": 2,
            "issuerName": "כאל",
            "brand": 2,
            "brandName": "ויזה",
            "isClub": false,
            "isPrepaid": false
        }
    }
}