Specify User Input

What is User Input

Dapi API might require user confirmation to complete the operation. You can consider this similar to 2-step verification. There are 5 types of input that could be requested from the user:

  • otp - This is either the OTP sent to the end user's device by the bank or an in app token in the user's bank app
  • secret_question - A set of questions set by the end user on a bank account
  • captcha - A captcha shown by the bank during bank operation
  • pin - Some bank accounts have hardware based device used to generate tokens for some bank operations
  • confirmation - Usually the user needs to open his app on the device to confirm an operation
  • token - An in app token similar to top.

When Is User Input Required

Confirmation can be required by any API endpoint. In other words, no matter which operation you are performing, API might require confirmation to complete it.

If user input is requested the response will look something like this:

{
    "operationID": "47204fa6-dca6-44a5-8111-6c6489a232a2",
    "success": true,
    "status": "user_input_required",
    "userInputs": [
    {
      "answer": "",
      "id": "otp",
      "index": 0,
      "query": "Please enter a Smart Pass Token from your ENBD mobile application"
    }
    ]
}

📘

Format of userInput query

UserInput query is always in a text format apart from the captcha type. In case of a captcha the query field will hold a base64 encoded image.

Dapi might request specification of more than one type of user input in a single request. If this is the case, userInputs returned in the response will contain more than one object. See example below:

{
    "operationID": "47204fa6-dca6-44a5-8111-6c6489a232a2",
    "success": true,
    "status": "user_input_required",
    "userInputs": [
    {
      "answer": "",
      "id": "otp",
      "index": 0,
      "query": "Please enter a Smart Pass Token from your ENBD mobile application"
    },
     {
      "answer": "",
      "id": "pin",
      "index": 1,
      "query": "Please enter your pin"
    }
    ]
}

📘

Simultaneous userInputs

API might require more than one input to be specified at the same time for confirmation. Meaning, user might be requested to specify OTP and captcha in the single request.

How To Specify User Input

There is no separate endpoint to specify user input. The user input answer is sent to the same endpoint where initial request was done. For example:

if request to Get Balance responded with status user_input_required then follow-up request with the user input must be sent to Get Balance endpoint to continue the operation.

Here is an example for the same scenario:

Requesting Get Balance:

{
    "appSecret": "5e6a5c184cb15c5bbdca720da21a9dc1586d89789d44a77bb468efb095f1190c",
    "userSecret": "Tj56n40ZqoPepDpySGroisPRNpj/OO/ZI1QT90w/JKxVJtGgKiN05sEQRR/EMVTSlgH2ULt0SdrZcVQqPRheLZEgti6UHoy4aE/DvJ5QXiByLNE3Sx3Fohk4FPXJ5dew37saEUD7O3XdRZU2ZYDLJ5NZl+po92DJ4FQoxDj/MX2ttCnA7W5r358f0tbII/jE0j1kPdr7EEBadV8NAnIRzKp60/ASJeLtEvPCFRc1lpkYIT+Gm5GuXFUUWj9BWT1lvpAd3BYa1MCtOv3Bv6OvSNqAp7M24ZQBrkz6ItkHYRtus9UMqtaEqiPyiJiUAgwqpQmepuy/hKbdgNw7uEt7botiUrhEE+HzcISkh0Tlf/WpCU9x8vyWJLhtQTjJ7NQ1VTTob1weogni1koE5TwiaXlJTjghEQdCLg2xu/SMeWlgyiHMLjrLHhIUnKb7z8Et6U0gtpYds6Qb1TaUtU1Zwj8s+kl/q3z2qmAQc0qO0jD0uNJ0HX8jSl+lpjlMo0cGsb24sX6Hnhbqko5pNn2gnZtxXYVWXLg10IxKJYeGYWUh1iLIan6cVA7d1sfNLiMbKkvT9nP3+201tFJn6MTUTwvA453Q4z+Zba0UQkFkstfn9203N5rjSMrcx3LNv5uZT1CEHotRKZ9Xzagm7s+eKkRY9GCPxXkUZMqVMywNt8U=",
    "accountID": "yUZ3k5H6YRasdq1gf94fMrrMsOsnTDrB2uHm0JqEtq7Et2KbUO6ajpNN54E7KzGCcdBFcC4xYO8EbJGjIV7CWIlw==",
}

Get Balance response requiring userInput:

{
    "operationID": "47204fa6-dca6-44a5-8111-6c6489a232a2",
    "success": true,
    "status": "user_input_required",
    "userInputs": [
    {
      "answer": "",
      "id": "otp",
      "index": 0,
      "query": "Please enter a Smart Pass Token from your ENBD mobile application"
    }
    ]
}

Sending the second request to Get Balance will need to include:

  • the standard Get Balance request body including appSecret, userSecret and accountID
  • userInputs list from the previous response with the answer field filled out
  • operationID from the previous response
{
    "appSecret": "5e6a5c184cb15c5bbdca720da21a9dc1586d89789d44a77bb468efb095f1190c",
    "userSecret": "Tj56n40ZqoPepDpySGroisPRNpj/OO/ZI1QT90w/JKxVJtGgKiN05sEQRR/EMVTSlgH2ULt0SdrZcVQqPRheLZEgti6UHoy4aE/DvJ5QXiByLNE3Sx3Fohk4FPXJ5dew37saEUD7O3XdRZU2ZYDLJ5NZl+po92DJ4FQoxDj/MX2ttCnA7W5r358f0tbII/jE0j1kPdr7EEBadV8NAnIRzKp60/ASJeLtEvPCFRc1lpkYIT+Gm5GuXFUUWj9BWT1lvpAd3BYa1MCtOv3Bv6OvSNqAp7M24ZQBrkz6ItkHYRtus9UMqtaEqiPyiJiUAgwqpQmepuy/hKbdgNw7uEt7botiUrhEE+HzcISkh0Tlf/WpCU9x8vyWJLhtQTjJ7NQ1VTTob1weogni1koE5TwiaXlJTjghEQdCLg2xu/SMeWlgyiHMLjrLHhIUnKb7z8Et6U0gtpYds6Qb1TaUtU1Zwj8s+kl/q3z2qmAQc0qO0jD0uNJ0HX8jSl+lpjlMo0cGsb24sX6Hnhbqko5pNn2gnZtxXYVWXLg10IxKJYeGYWUh1iLIan6cVA7d1sfNLiMbKkvT9nP3+201tFJn6MTUTwvA453Q4z+Zba0UQkFkstfn9203N5rjSMrcx3LNv5uZT1CEHotRKZ9Xzagm7s+eKkRY9GCPxXkUZMqVMywNt8U=",
    "accountID": "yUZ3k5H6YRasdq1gf94fMrrMsOsnTDrB2uHm0JqEtq7Et2KbUO6ajpNN54E7KzGCcdBFcC4xYO8EbJGjIV7CWIlw==",
    "operationID": "47204fa6-dca6-44a5-8111-6c6489a232a2",
    "userInputs": [
        {
            "answer": "123456",
            "id": "otp",
            "index": 0,
            "query": "Please enter a Smart Pass Token from your ENBD mobile application"
        }
    ]
}

If user input was valid, API will return success response of the endpoint that requested confirmation. Meaning, after specifying user input for GetBalance endpoint, if successful you will receive user balance information in the response.

📘

Note

API might request user input several times in a row. In other words, once you submit the user input, API might follow up with new type of input to be specified again before performing the operation.