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

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

  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 (Isracaredit/ 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

  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_-

  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.
     • 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
  

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

See Errors

Example

Basic Sale Transaction

Request

{
    "jsonrpc": "2.0",
    "method": "startTransaction",
    "id": "1234567890",
    "params": {
        "paymentMethod": "CREDIT_CARD",
        "transactionType": "SALE",
        "referenceId": "abcdef123456",
        "amount": 1000,
        "currency": 376
    }
}

Response

{
    "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

{`
    "jsonrpc": "2.0",
    "method": "startTransaction",
    "id": "1234567890",
    "params": {
        "paymentMethod": "CREDIT_CARD",
        "transactionType": "SALE",
        "referenceId": "abcdef123456",
        "amount": 1000,
        "currency": 376,
        "notifyUpdate": true
    }
}

Response

{
    "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
        }
    }
}