NextStep Server RESTful API Reference

Edit on Github Send Feedback v0.24.1

PowerAuth Web Flow communicates with the Next Step Server via a REST API to resolve the next step in the authentication process. This chapter defines the REST API implemented by Next Step Server and consumed by the Web Flow Server during authentication. The REST API can be also used by other components.

The Next Step API can list available authentication methods and enable/disable authentication methods per user. Authentication method configuration can be updated - for instance the activation ID of registered user device is set for the Mobile Token authentication method.

The Next Step API is also used by other components involved in the authentication process (e.g. Mobile Token which uses the API indirectly through Web Flow or a party initiating a new operation). The API can be used to query operation details, create an operation, update an operation (move it to the next step) as well as update operation form data and set chosen authentication method as the user progresses in the authentication and authorization process.

Following topics are covered in this chapter:

Status codes and error handling
Service status
Authentication methods
Operations
Organizations
- Organization list
- Organization detail

You can access the generated REST API documentation in deployed Next Step:

http[s]://[host]:[port]/powerauth-nextstep/swagger-ui.html

Status codes and error handling

PowerAuth Web Flow Server uses a unified format for error response body, accompanied with an appropriate HTTP status code. Besides the HTTP error codes that application server may return regardless of server application (such as 404 when resource is not found or 503 when server is down).

The list of error status codes:

Code	Description
200	OK response - REST API call succeeded
500	Server error - details in the message

All error responses that are produced by the Next Step Server have following body:

{
    "status": "ERROR",
    "responseObject": {
        "code": "ERROR_CODE",
        "message": "ERROR_MESSAGE_I18N_KEY"
    }
}

Service Status

Get a system status response, with basic information about the running application.

Method	`GET`
Resource URI	/api/service/status

Response

{
    "status" : "OK",
    "responseObject": {
        "applicationName" : "powerauth-nextstep",
        "applicationDisplayName" : "PowerAuth Next Step Server",
        "applicationEnvironment" : "",
        "version" : "0.22.0",
        "buildTime" : "2019-06-11T09:34:52Z",
        "timestamp" : "2019-06-14T14:54:14Z"
    }  
}

applicationName - Application name.
applicationDisplayName - Application display name.
applicationEnvironment - Application environment.
version - Version of Next Step.
buildTime - Timestamp when powerauth-nextstep.war file was created.
timestamp - Response timestamp.

Authentication methods

List authentication methods

Lists all authentication methods supported by the server.

Method	`POST`
Resource URI	`/auth-method/list`

Request

Headers:
- Content-Type: application/json

{
  "requestObject": {
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "authMethods": [
      {
        "authMethod": "INIT",
        "hasUserInterface": false,
        "displayNameKey": null,
        "hasMobileToken": false
      },
      {
        "authMethod": "USER_ID_ASSIGN",
        "hasUserInterface": false,
        "displayNameKey": null,
        "hasMobileToken": false
      },
      {
        "authMethod": "USERNAME_PASSWORD_AUTH",
        "hasUserInterface": true,
        "displayNameKey": "method.usernamePassword",
        "hasMobileToken": false
      },
      {
        "authMethod": "SHOW_OPERATION_DETAIL",
        "hasUserInterface": true,
        "displayNameKey": "method.showOperationDetail",
        "hasMobileToken": false
      },
      {
        "authMethod": "POWERAUTH_TOKEN",
        "hasUserInterface": true,
        "displayNameKey": "method.powerauthToken",
        "hasMobileToken": true
      },
      {
        "authMethod": "SMS_KEY",
        "hasUserInterface": true,
        "displayNameKey": "method.smsKey",
        "hasMobileToken": false
      },
      {
        "authMethod": "CONSENT",
        "hasUserInterface": true,
        "displayNameKey": "method.consent",
        "hasMobileToken": false
      },
      {
        "authMethod": "LOGIN_SCA",
        "hasUserInterface": true,
        "displayNameKey": "method.loginSca",
        "hasMobileToken": true
      },
      {
        "authMethod": "APPROVAL_SCA",
        "hasUserInterface": true,
        "displayNameKey": "method.approvalSca",
        "hasMobileToken": true
      }
    ]
  }
}

List authentication methods enabled for given user

Lists all authentication methods enabled for given user.

Method	`POST`
Resource URI	`/user/auth-method/list`

Request

Headers:
- Content-Type: application/json

{
  "requestObject": {
    "userId": "12345678"
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "userAuthMethods": [
      {
        "userId": "12345678",
        "authMethod": "INIT",
        "hasUserInterface": false,
        "displayNameKey": null,
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "USER_ID_ASSIGN",
        "hasUserInterface": false,
        "displayNameKey": null,
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "USERNAME_PASSWORD_AUTH",
        "hasUserInterface": true,
        "displayNameKey": "method.usernamePassword",
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "SHOW_OPERATION_DETAIL",
        "hasUserInterface": true,
        "displayNameKey": "method.showOperationDetail",
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "POWERAUTH_TOKEN",
        "hasUserInterface": true,
        "displayNameKey": "method.powerauthToken",
        "hasMobileToken": true,
        "config": {
          "activationId": "1629d4c7-6b17-41e3-bce1-e184e94921d2"
        }
      },
      {
        "userId": "12345678",
        "authMethod": "SMS_KEY",
        "hasUserInterface": true,
        "displayNameKey": "method.smsKey",
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "CONSENT",
        "hasUserInterface": true,
        "displayNameKey": "method.consent",
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "LOGIN_SCA",
        "hasUserInterface": true,
        "displayNameKey": "method.loginSca",
        "hasMobileToken": true,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "APPROVAL_SCA",
        "hasUserInterface": true,
        "displayNameKey": "method.approvalSca",
        "hasMobileToken": true,
        "config": null
      }
    ]
  }
}

Enable an authentication method for given user

Enables an authentication method for given user and lists all authentication methods enabled for given user after the authentication method has been enabled.

Method	`POST`
Resource URI	`/user/auth-method`

Request

The request contains three parameters:

userId - identification of the user
authMethod - name of the authentication method
config - configuration of the authentication method

Currently the only supported configuration is in the POWERAUTH_TOKEN method and it contains activationId, as seen on the sample request below.

Headers:
- Content-Type: application/json

{
  "requestObject": {
    "userId": "12345678",
    "authMethod": "POWERAUTH_TOKEN",
    "config": {
      "activationId": "26c94bf8-f594-4bd8-9c51-93449926b644"
    }
  }
}

For other authentication methods use the following configuration:

{
  "requestObject": {
    "userId": "12345678",
    "authMethod": "SMS_KEY",
    "config": null
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "userAuthMethods": [
      {
        "userId": "12345678",
        "authMethod": "INIT",
        "hasUserInterface": false,
        "displayNameKey": null,
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "USER_ID_ASSIGN",
        "hasUserInterface": false,
        "displayNameKey": null,
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "USERNAME_PASSWORD_AUTH",
        "hasUserInterface": true,
        "displayNameKey": "method.usernamePassword",
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "SHOW_OPERATION_DETAIL",
        "hasUserInterface": true,
        "displayNameKey": "method.showOperationDetail",
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "POWERAUTH_TOKEN",
        "hasUserInterface": true,
        "displayNameKey": "method.powerauthToken",
        "hasMobileToken": true,
        "config": {
          "activationId": "26c94bf8-f594-4bd8-9c51-93449926b644"
        }
      },
      {
        "userId": "12345678",
        "authMethod": "SMS_KEY",
        "hasUserInterface": true,
        "displayNameKey": "method.smsKey",
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "CONSENT",
        "hasUserInterface": true,
        "displayNameKey": "method.consent",
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "LOGIN_SCA",
        "hasUserInterface": true,
        "displayNameKey": "method.loginSca",
        "hasMobileToken": true,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "APPROVAL_SCA",
        "hasUserInterface": true,
        "displayNameKey": "method.approvalSca",
        "hasMobileToken": true,
        "config": null
      }
    ]
  }
}

Disable an authentication method for given user

Disables an authentication method for given user and lists all authentication methods enabled for given user after the authentication method has been disabled.

Method	`DELETE`
Resource URI	`/user/auth-method`

Alternative with POST method for environments which do not allow DELETE methods:

Method	`POST`
Resource URI	`/user/auth-method/delete`

Request

Headers:
- Content-Type: application/json

{
  "requestObject": {
    "userId": "12345678",
    "authMethod": "POWERAUTH_TOKEN"
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "userAuthMethods": [
      {
        "userId": "12345678",
        "authMethod": "INIT",
        "hasUserInterface": false,
        "displayNameKey": null,
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "USER_ID_ASSIGN",
        "hasUserInterface": false,
        "displayNameKey": null,
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "USERNAME_PASSWORD_AUTH",
        "hasUserInterface": true,
        "displayNameKey": "method.usernamePassword",
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "SHOW_OPERATION_DETAIL",
        "hasUserInterface": true,
        "displayNameKey": "method.showOperationDetail",
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "SMS_KEY",
        "hasUserInterface": true,
        "displayNameKey": "method.smsKey",
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "CONSENT",
        "hasUserInterface": true,
        "displayNameKey": "method.consent",
        "hasMobileToken": false,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "LOGIN_SCA",
        "hasUserInterface": true,
        "displayNameKey": "method.loginSca",
        "hasMobileToken": true,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "APPROVAL_SCA",
        "hasUserInterface": true,
        "displayNameKey": "method.approvalSca",
        "hasMobileToken": true,
        "config": null
      }
    ]
  }
}

Operations

Operation detail contains following data:

operationId - unique ID of the operation, it is either set while creating an operation or it is generated (field is required, value is optional, for generated operation use null as value)
operationName - name of the operations based on the purpose of the operation - different steps are defined for each operation name (required)
userId - ID of user in case the user has been already authorized (optional)
organizationId - ID of organization in case the user has been already authorized (optional)
result - result of the last authentication step: CONTINUE, FAILED or DONE (required)
timestampCreated - timestamp when operation was created (required)
timestampExpires - timestamp when operation expires (required)
operationData - arbitrary string which contains data related to this operation, this data is not used during authorization and authentication (required). Since Web Flow version 0.20.0 the structure of operation data is specified for easier interpretation of data in Mobile token.
steps - next steps for the operation (required)
history - operation history with completed authentication steps (required)
afsActions - AFS actions executed for the operation (optional)
formData - data displayed by the UI as well as data gathered from the user responses (required, discussed in details below)
chosenAuthMethod - authentication method chosen in current authentication step (optional)
remainingAttempts - remaining attempts for current authentication step (optional)
applicationContext - application context with information about application which triggered the operation, used when generating the consent form (optional)
expired - whether operation was expired at the time of generating response (optional)

Example of complete operation detail:

{
  "status": "OK",
  "responseObject": {
    "operationId": "b7ecf869-2ebb-44bf-ae0e-0963e9d6d46f",
    "operationName": "authorize_payment_sca",
    "userId": "12345678",
    "organizationId": "RETAIL",
    "accountStatus": "ACTIVE",
    "result": "CONTINUE",
    "timestampCreated": "2019-11-01T15:35:37+0000",
    "timestampExpires": "2019-11-01T15:41:16+0000",
    "operationData": "A1*A100CZK*Q238400856/0300**D20190629*NUtility Bill Payment - 05/2019",
    "steps": [
      {
        "authMethod": "CONSENT",
        "params": []
      }
    ],
    "history": [
      {
        "authMethod": "INIT",
        "authResult": "CONTINUE",
        "requestAuthStepResult": "CONFIRMED"
      },
      {
        "authMethod": "LOGIN_SCA",
        "authResult": "CONTINUE",
        "requestAuthStepResult": "CONFIRMED"
      },
      {
        "authMethod": "APPROVAL_SCA",
        "authResult": "CONTINUE",
        "requestAuthStepResult": "CONFIRMED"
      }
    ],
    "afsActions": [
      {
        "action": "LOGIN_INIT",
        "stepIndex": 1,
        "afsLabel": "2FA",
        "afsResponseApplied": false,
        "requestExtras": {},
        "responseExtras": {}
      },
      {
        "action": "LOGIN_AUTH",
        "stepIndex": 1,
        "afsLabel": "2FA",
        "afsResponseApplied": false,
        "requestExtras": {},
        "responseExtras": {}
      },
      {
        "action": "APPROVAL_INIT",
        "stepIndex": 1,
        "afsLabel": "1FA",
        "afsResponseApplied": true,
        "requestExtras": {},
        "responseExtras": {}
      },
      {
        "action": "APPROVAL_AUTH",
        "stepIndex": 1,
        "afsLabel": "2FA",
        "afsResponseApplied": false,
        "requestExtras": {},
        "responseExtras": {}
      }
    ],
    "formData": {
      "title": {
        "id": "operation.title",
        "message": null
      },
      "greeting": {
        "id": "operation.greeting",
        "message": null
      },
      "summary": {
        "id": "operation.summary",
        "message": null
      },
      "config": [],
      "banners": [],
      "parameters": [
        {
          "type": "AMOUNT",
          "id": "operation.amount",
          "label": null,
          "valueFormatType": "AMOUNT",
          "formattedValues": {},
          "amount": 100,
          "currency": "CZK",
          "currencyId": "operation.currency"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.account",
          "label": null,
          "valueFormatType": "ACCOUNT",
          "formattedValues": {},
          "value": "238400856/0300"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.dueDate",
          "label": null,
          "valueFormatType": "DATE",
          "formattedValues": {},
          "value": "2019-06-29"
        },
        {
          "type": "NOTE",
          "id": "operation.note",
          "label": null,
          "valueFormatType": "TEXT",
          "formattedValues": {},
          "note": "Utility Bill Payment - 05/2019"
        }
      ],
      "dynamicDataLoaded": false,
      "userInput": {
        "smsFallback.enabled": "true",
        "operation.bankAccountChoice": "CZ4012340000000012345678",
        "operation.bankAccountChoice.disabled": "true"
      }
    },
    "chosenAuthMethod": "CONSENT",
    "remainingAttempts": 5,
    "applicationContext": {
      "id": "democlient",
      "name": "Demo application",
      "description": "Web Flow demo application",
      "originalScopes": [
        "pisp"
      ],
      "extras": {
        "applicationOwner": "Wultra"
      }
    },
    "expired": false
  }
}

Operation formData

Operations contain formData which is a generic structure for storing input and output data for the operation.

The formData contains following sections:

static data - this data is set when the operation is created (required)
dynamic data - this data is added as the operation progresses (optional)
user input - this data contains gathered inputs from the user as the authentication and authorization progresses (optional)

The static part of formData contains data related to the operation known when operation is initiated. For instance in case of a payment, the static data contains information about the payment such as title, amount, currency, target account and message to display to the user in the following structure:

{
  "formData": {
      "title": {
        "id": "operation.title",
        "message": "Confirm Payment"
      },
      "greeting": {
        "id": "operation.greeting",
        "message": "Hello,\nplease confirm following payment:"
      },
      "summary": {
        "id": "operation.summary",
        "message": "Hello, please confirm payment 100 CZK to account 238400856/0300."
      },
      "config": [],
      "banners": [],
      "parameters": [
        {
          "type": "AMOUNT",
          "id": "operation.amount",
          "label": "Amount",
          "valueFormatType": "AMOUNT",
          "formattedValues": {
            "amount": "100.00",
            "currency": "CZK"
          },
          "amount": 100,
          "currency": "CZK",
          "currencyId": "operation.currency"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.account",
          "label": "To Account",
          "valueFormatType": "ACCOUNT",
          "formattedValues": {
            "value": "238400856/0300"
          }
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.dueDate",
          "label": "Due Date",
          "valueFormatType": "DATE",
          "formattedValues": {
            "value": "Jun 29, 2019"
          },
          "value": "2019-06-29"
        },
        {
          "type": "NOTE",
          "id": "operation.note",
          "label": "Note",
          "valueFormatType": "TEXT",
          "formattedValues": {
            "value": "Utility Bill Payment - 05/2019"
          },          
          "note": "Utility Bill Payment - 05/2019"
        },
        {
          "type": "HEADING",
          "id": "operation.heading",
          "label": null,
          "valueFormatType": "LOCALIZED_TEXT",
          "formattedValues": {
            "value": "Confirm Payment"
          },            
          "value": "operation.title"
        }
      ],
      "dynamicDataLoaded": false,
      "userInput": { 
      }
   }
}

The usage of static formData:

title - displayed as title on the page with operation details
- field is required
- id is the localization key
- value is the localized text displayed on the page
greeting - displayed as a greeting message in the web application without operation details
- field is required
- id is the localization key
- value is the localized text displayed on the page
summary - displayed as a summary message in the push message sent to mobile device
- field is required
- id is the localization key
- value is the localized text displayed in the push message
config - configures individual form fields (e.g. default values, enabled/disabled state, etc.)
- field is required, however the config list can be empty
banners - banners which can be displayed above form
parameters - operation parameters which are displayed on the page with operation details
- field is required, however the parameter list can be empty

Following parameter types are available:

AMOUNT - contains information about amount in this operation including currency
- field is optional
- id is used both for field identification as well as the localization key
- label is the displayed localized text
- valueFormatType specifies the format type
- formattedValue is the formatted value based on format type
- amount is displayed next to the label
- currency is displayed next to the amount
- currencyId is used internally for localization
NOTE - contains text message related to the operation
- field is optional
- id is used both for field identification as well as the localization key
- label is the displayed localized text
- valueFormatType specifies the format type
- formattedValue is the formatted value based on format type
- note is the text message displayed next to the label
KEY_VALUE
- field is optional
- id is used both for field identification as well as the localization key
- label is the displayed localized text
- valueFormatType specifies the format type
- formattedValue is the formatted value based on format type
- value is the text displayed next to the label
HEADING
- field is optional
- id is used both for field identification as well as the localization key
- label is ignored
- value contains heading text
- valueFormatType specifies the format type
- formattedValue is the formatted heading text based on format type

The dynamic part of formData contains additional data which is loaded once the user is authenticated. For instance in case of a payment, the dynamic data can contain choice of bank accounts available for the user with their balances:

{
  "formData": {
    "parameters": [
      {
        "type": "BANK_ACCOUNT_CHOICE",
        "id": "operation.bankAccountChoice",
        "label": "From Your Account",
        "bankAccounts": [
          {
            "number": "12345678/1234",
            "accountId": "CZ4012340000000012345678",
            "name": "Běžný účet v CZK",
            "balance": 24394.52,
            "currency": "CZK",
            "usableForPayment": false,
            "unusableForPaymentReason": null
          },
          {
            "number": "87654321/4321",
            "accountId": "CZ4043210000000087654321",
            "name": "Spořící účet v CZK",
            "balance": 158121.1,
            "currency": "CZK",
            "usableForPayment": false,
            "unusableForPaymentReason": null
          },
          {
            "number": "44444444/1111",
            "accountId": "CZ4011110000000044444444",
            "name": "Spořící účet v EUR",
            "balance": 1.9,
            "currency": "EUR",
            "usableForPayment": false,
            "unusableForPaymentReason": "Low account balance"
          }
        ],
        "enabled": true,
        "defaultValue": "CZ4012340000000012345678"
      }
    ]
  }
}

Following parameter types are available:

BANK_ACCOUNT_CHOICE
- field is optional
- id is used both for field identification as well as the localization key
- label is the displayed localized text
- bankAccounts list is required when BANK_ACCOUNT_CHOICE parameter is specified, however it can be empty

Bank account details:

number - required, account number in human readable format
name - required, account name
balance - required, account balance
currency - required, account currency
usableForPayment - required, whether account can be used for payment, in case value is false, unusableForPaymentReason is displayed
unusableForPaymentReason - optional when usableForPayment = false, otherwise it is required, field explains reason why account is unusable for payment

When dynamic form data is loaded, the formData structure contains following data:

{
  "formData": {
    "dynamicDataLoaded": true
  }
}

Dynamic formData may not be loaded because it is required only for specific steps such as operation review. In this case the value is:

{
  "formData": {
    "dynamicDataLoaded": false
  }
}

The form fields can be configured in the config section as follows:

{
  "formData": {
    "config" : [ {
      "id" : "operation.bankAccountChoice",
      "enabled" : false,
      "defaultValue" : "CZ4043210000000087654321"
    } ]
  }
}

Each configuration item contains following fields:

id - id is used for field identification, same as id used in parameters
enabled - whether the field is enabled or disabled (default value = true)
defaultValue - default value of the field (default value = null)

The formData uses userInput JSON structure while gathering input from the user as the operation progresses:

{
  "formData": {
    "userInput": {
      "operation.bankAccountChoice": "CZ4012340000000012345678",
      "operation.bankAccountChoice.disabled": "true"
    }
  }
}

The userInput part of formData is optional - empty value of userInput is:

{
  "formData": {
    "userInput": {
    }
  }
}

Chosen authentication method for current step is stored in formData in case it is available:

{
  "formData": {
    "chosenAuthMethod": "POWERAUTH_TOKEN"
  }
}

Null value is used when authentication method has not been chosen for current step:

{
  "formData": {
    "chosenAuthMethod": null
  }
}

Create an operation

Creates an operation in Next Step server.

Documentation for operation data is available in a separate document.

Method	`POST`
Resource URI	`/operation`

Request - AISP

Headers:
- Content-Type: application/json

{
  "requestObject": {
    "operationName": "login",
    "operationData": "A2",
    "externalTransactionId": "1234567890",
    "formData": {
      "title": {
        "id": "login.title"
      },
      "greeting": {
        "id": "login.greeting"
      },
      "summary": {
        "id": "login.summary"
      }
    },
    "applicationContext": {
      "id": "democlient",
      "name": "Demo application",
      "description": "Web Flow demo application",
      "originalScopes": ["pisp"],
      "extras": {
        "applicationOwner": "Wultra"
      }
    }
  }
}

Request - PISP

Headers:
- Content-Type: application/json

{
  "requestObject": {
    "operationName": "authorize_payment",
    "operationId": null,
    "organizationId": null,
    "externalTransactionId": "1234567890",
    "operationData": "A1*A100CZK*Q238400856/0300**D20190629*NUtility Bill Payment - 05/2019",
    "params": [],
    "formData": {
      "title": {
        "id": "operation.title",
        "value": null
      },
      "greeting": {
        "id": "operation.greeting",
        "value": null
      },
      "summary": {
        "id": "operation.summary",
        "value": null
      },
      "config": [],
      "parameters": [
        {
          "type": "AMOUNT",
          "id": "operation.amount",
          "label": null,
          "valueFormatType": "AMOUNT",
          "formattedValues": {},
          "amount": 100,
          "currency": "CZK",
          "currencyId": "operation.currency"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.account",
          "label": null,
          "valueFormatType": "ACCOUNT",
          "formattedValues": {},
          "value": "238400856/0300"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.dueDate",
          "label": null,
          "valueFormatType": "DATE",
          "formattedValues": {},
          "value": "2019-06-29"
        },
        {
          "type": "NOTE",
          "id": "operation.note",
          "label": null,
          "valueFormatType": "TEXT",
          "formattedValues": {},
          "note": "Utility Bill Payment - 05/2019"
        }
      ]
    },
      "applicationContext": {
        "id": "democlient",
        "name": "Demo application",
        "description": "Web Flow demo application",
        "originalScopes": ["pisp"],
        "extras": {
          "applicationOwner": "Wultra"
        }
    }
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

AISP:

{
  "status": "OK",
  "responseObject": {
    "operationId": "ec039314-7560-470a-b226-116c712e8fb3",
    "operationName": "login",
    "organizationId": null,
    "externalTransactionId": "1234567890",
    "result": "CONTINUE",
    "resultDescription": null,
    "timestampCreated": "2019-07-30T12:51:28+0000",
    "timestampExpires": "2019-07-30T12:56:28+0000",
    "operationData": null,
    "steps": [
      {
        "authMethod": "USER_ID_ASSIGN",
        "params": []
      },
      {
        "authMethod": "USERNAME_PASSWORD_AUTH",
        "params": []
      }
    ],
    "formData": {
      "title": {
        "id": "login.title",
        "message": null
      },
      "greeting": {
        "id": "login.greeting",
        "message": null
      },
      "summary": {
        "id": "login.summary",
        "message": null
      },
      "config": [],
      "banners": [],
      "parameters": [],
      "dynamicDataLoaded": false,
      "userInput": {}
    },
    "expired": false
  }
}

PISP:

{
  "status": "OK",
  "responseObject": {
    "operationId": "f415a617-f7c0-4800-8436-f85eb075eb6f",
    "operationName": "authorize_payment",
    "organizationId": null,
    "externalTransactionId": "1234567890",
    "result": "CONTINUE",
    "resultDescription": null,
    "timestampCreated": "2019-07-30T12:52:35+0000",
    "timestampExpires": "2019-07-30T12:57:35+0000",
    "operationData": null,
    "steps": [
      {
        "authMethod": "USER_ID_ASSIGN",
        "params": []
      },
      {
        "authMethod": "USERNAME_PASSWORD_AUTH",
        "params": []
      }
    ],
    "formData": {
      "title": {
        "id": "operation.title",
        "message": null
      },
      "greeting": {
        "id": "operation.greeting",
        "message": null
      },
      "summary": {
        "id": "operation.summary",
        "message": null
      },
      "config": [],
      "banners": [],
      "parameters": [
        {
          "type": "AMOUNT",
          "id": "operation.amount",
          "label": null,
          "valueFormatType": "AMOUNT",
          "formattedValues": {},
          "amount": 100,
          "currency": "CZK",
          "currencyId": "operation.currency"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.account",
          "label": null,
          "valueFormatType": "ACCOUNT",
          "formattedValues": {},
          "value": "238400856/0300"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.dueDate",
          "label": null,
          "valueFormatType": "DATE",
          "formattedValues": {},
          "value": "2019-06-29"
        },
        {
          "type": "NOTE",
          "id": "operation.note",
          "label": null,
          "valueFormatType": "TEXT",
          "formattedValues": {},
          "note": "Utility Bill Payment - 05/2019"
        }
      ],
      "dynamicDataLoaded": false,
      "userInput": {}
    },
    "expired": false
  }
}

Update an operation

Updates an operation in Next Step server.

Method	`PUT`
Resource URI	`/operation`

Alternative with POST method for environments which do not allow PUT methods:

Method	`POST`
Resource URI	`/operation/update`

Request

Headers:
- Content-Type: application/json

{
  "requestObject": {
    "operationId": "4e02b39b-1ecb-440a-a942-cc27bc07d203",
    "userId": "12345678",
    "organizationId": "RETAIL",
    "authMethod": "USERNAME_PASSWORD_AUTH",
    "authStepResult": "CONFIRMED",
    "authStepResultDescription": null,
    "params": []
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "operationId": "4e02b39b-1ecb-440a-a942-cc27bc07d203",
    "operationName": "authorize_payment",
    "userId": "12345678",
    "organizationId": "RETAIL",
    "externalTransactionId": "1234567890",
    "result": "CONTINUE",
    "resultDescription": null,
    "timestampCreated": "2018-06-28T12:20:28+0000",
    "timestampExpires": "2018-06-28T12:20:43+0000",
    "operationData": "A1*A100CZK*Q238400856/0300**D20190629*NUtility Bill Payment - 05/2019",
    "steps": [
      {
        "authMethod": "SMS_KEY",
        "params": []
      }
    ],
    "formData": {
      "title": {
        "id": "operation.title",
        "value": null
      },
      "greeting": {
        "id": "operation.greeting",
        "value": null
      },
      "summary": {
        "id": "operation.summary",
        "value": null
      },
      "config": [],
      "parameters": [
        {
          "type": "AMOUNT",
          "id": "operation.amount",
          "label": null,
          "valueFormatType": "AMOUNT",
          "formattedValues": {},
          "amount": 100,
          "currency": "CZK",
          "currencyId": "operation.currency"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.account",
          "label": null,
          "valueFormatType": "ACCOUNT",
          "formattedValues": {},
          "value": "238400856/0300"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.dueDate",
          "label": null,
          "valueFormatType": "DATE",
          "formattedValues": {},
          "value": "2019-06-29"
        },
        {
          "type": "NOTE",
          "id": "operation.note",
          "label": null,
          "valueFormatType": "TEXT",
          "formattedValues": {},
          "note": "Utility Bill Payment - 05/2019"
        }
      ]
    },
    "expired": false
  }
}

Operation detail

Retrieves detail of an operation in the Next Step server.

Method	`POST`
Resource URI	`/operation/detail`

Request

Headers:
- Content-Type: application/json

{
  "requestObject" : {
    "operationId" : "0861a423-ac06-4bcb-a426-2052872163d3"
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "operationId": "0861a423-ac06-4bcb-a426-2052872163d3",
    "operationName": "authorize_payment_sca",
    "userId": "12345678",
    "organizationId": "RETAIL",
    "result": "CONTINUE",
    "timestampCreated": "2019-07-30T12:36:19+0000",
    "timestampExpires": "2019-07-30T12:41:40+0000",
    "operationData": "A1*A100CZK*Q238400856/0300**D20190629*NUtility Bill Payment - 05/2019",
    "steps": [
      {
        "authMethod": "LOGIN_SCA",
        "params": []
      }
    ],
    "history": [
      {
        "authMethod": "INIT",
        "authResult": "CONTINUE",
        "requestAuthStepResult": "CONFIRMED"
      }
    ],
    "formData": {
      "title": {
        "id": "operation.title",
        "message": null
      },
      "greeting": {
        "id": "operation.greeting",
        "message": null
      },
      "summary": {
        "id": "operation.summary",
        "message": null
      },
      "config": [],
      "banners": [],
      "parameters": [
        {
          "type": "AMOUNT",
          "id": "operation.amount",
          "label": null,
          "valueFormatType": "AMOUNT",
          "formattedValues": {},
          "amount": 100,
          "currency": "CZK",
          "currencyId": "operation.currency"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.account",
          "label": null,
          "valueFormatType": "ACCOUNT",
          "formattedValues": {},
          "value": "238400856/0300"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.dueDate",
          "label": null,
          "valueFormatType": "DATE",
          "formattedValues": {},
          "value": "2019-06-29"
        },
        {
          "type": "NOTE",
          "id": "operation.note",
          "label": null,
          "valueFormatType": "TEXT",
          "formattedValues": {},
          "note": "Utility Bill Payment - 05/2019"
        }
      ],
      "dynamicDataLoaded": false,
      "userInput": {
        "smsFallback.enabled": "true"
      }
    },
    "chosenAuthMethod": null,
    "remainingAttempts": 3,
    "applicationContext": {
      "id": "democlient",
      "name": "Demo application",
      "description": "Web Flow demo application",
      "originalScopes": ["pisp"],
      "extras": {
        "applicationOwner": "Wultra"
      }
    },
    "expired": false
  }
}

List pending operations

Lists pending operation for given user and authentication method.

Method	`POST`
Resource URI	`/user/operation/list`

Request

Headers:
- Content-Type: application/json

{
  "requestObject" : {
    "userId" : "12345678",
    "mobileTokenOnly" : true
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": [
    {
      "operationId": "d7d9910e-b047-4352-b2b3-f1fa30d03f3a",
      "operationName": "authorize_payment_sca",
      "userId": "12345678",
      "organizationId": "RETAIL",
      "accountStatus": "ACTIVE",
      "result": "CONTINUE",
      "timestampCreated": "2019-07-30T12:57:28+0000",
      "timestampExpires": "2019-07-30T13:02:28+0000",
      "operationData": "A1*A100CZK*Q238400856/0300**D20190629*NUtility Bill Payment - 05/2019",
      "steps": [],
      "history": [
        {
          "authMethod": "INIT",
          "authResult": "CONTINUE",
          "requestAuthStepResult": "CONFIRMED"
        }
      ],
      "formData": {
        "title": {
          "id": "operation.title",
          "message": null
        },
        "greeting": {
          "id": "operation.greeting",
          "message": null
        },
        "summary": {
          "id": "operation.summary",
          "message": null
        },
        "config": [],
        "banners": [],
        "parameters": [
          {
            "type": "AMOUNT",
            "id": "operation.amount",
            "label": null,
            "valueFormatType": "AMOUNT",
            "formattedValues": {},
            "amount": 100,
            "currency": "CZK",
            "currencyId": "operation.currency"
          },
          {
            "type": "KEY_VALUE",
            "id": "operation.account",
            "label": null,
            "valueFormatType": "ACCOUNT",
            "formattedValues": {},
            "value": "238400856/0300"
          },
          {
            "type": "KEY_VALUE",
            "id": "operation.dueDate",
            "label": null,
            "valueFormatType": "DATE",
            "formattedValues": {},
            "value": "2019-06-29"
          },
          {
            "type": "NOTE",
            "id": "operation.note",
            "label": null,
            "valueFormatType": "TEXT",
            "formattedValues": {},
            "note": "Utility Bill Payment - 05/2019"
          }
        ],
        "dynamicDataLoaded": false,
        "userInput": {}
      },
      "chosenAuthMethod": "LOGIN_SCA",
      "remainingAttempts": null,
      "applicationContext": {
        "id": "democlient",
        "name": "Demo application",
        "description": "Web Flow demo application",
        "originalScopes": ["pisp"],
        "extras": {
          "applicationOwner": "Wultra"
        }
      },
      "expired": false
    }
  ]
}

Lookup operations by external transaction ID

Find all operations with matching external transaction ID.

Method	`POST`
Resource URI	`/operation/lookup/external`

Request

Headers:
- Content-Type: application/json

{
  "requestObject" : {
    "externalTransactionId" : "12345678"
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "operations": [
      {
        "operationId": "e6d3a5e7-e291-42f7-bd46-49d9fbac4282",
        "operationName": "authorize_payment",
        "userId": null,
        "organizationId": "RETAIL",
        "accountStatus": "ACTIVE",
        "externalTransactionId": "12345678",
        "result": "CONTINUE",
        "timestampCreated": "2020-01-28T15:58:11+0000",
        "timestampExpires": "2020-01-28T16:03:11+0000",
        "operationData": "A1*A100CZK*Q238400856/0300**D20170629*NUtility Bill Payment - 05/2017",
        "steps": [],
        "history": [
          {
            "authMethod": "INIT",
            "authResult": "CONTINUE",
            "requestAuthStepResult": "CONFIRMED"
          }
        ],
        "afsActions": [],
        "formData": {
          "title": {
            "id": "operation.title",
            "message": null
          },
          "greeting": {
            "id": "operation.greeting",
            "message": null
          },
          "summary": {
            "id": "operation.summary",
            "message": null
          },
          "config": [],
          "banners": [],
          "parameters": [
            {
              "type": "AMOUNT",
              "id": "operation.amount",
              "label": null,
              "valueFormatType": "AMOUNT",
              "formattedValues": {},
              "amount": 100,
              "currency": "CZK",
              "currencyId": "operation.currency"
            },
            {
              "type": "KEY_VALUE",
              "id": "operation.account",
              "label": null,
              "valueFormatType": "ACCOUNT",
              "formattedValues": {},
              "value": "238400856/0300"
            },
            {
              "type": "KEY_VALUE",
              "id": "operation.dueDate",
              "label": null,
              "valueFormatType": "DATE",
              "formattedValues": {},
              "value": "2017-06-29"
            },
            {
              "type": "NOTE",
              "id": "operation.note",
              "label": null,
              "valueFormatType": "TEXT",
              "formattedValues": {},
              "note": "Utility Bill Payment - 05/2017"
            }
          ],
          "dynamicDataLoaded": false,
          "userInput": {}
        },
        "chosenAuthMethod": null,
        "remainingAttempts": null,
        "applicationContext": {
          "id": "democlient",
          "name": "Demo application",
          "description": "Web Flow demo application",
          "originalScopes": ["pisp"],
          "extras": {
            "applicationOwner": "Wultra"
          }
        },
        "expired": false
      }
    ]
  }
}

Update operation formData

Updates operation formData for given operation. Only the userInput part of formData can be currently updated by the clients.

Method	`PUT`
Resource URI	`/operation/formData`

Alternative with POST method for environments which do not allow PUT methods:

Method	`POST`
Resource URI	`/operation/formData/update`

Request

Headers:
- Content-Type: application/json

{
  "formData": {
    "title": {
      "id": "operation.title",
      "message": "Confirm Payment"
    },
    "greeting": {
      "id": "operation.greeting",
      "message": "Hello,\nplease confirm following payment:"
    },
    "summary": {
      "id": "operation.summary",
      "message": "Hello, please confirm payment 100 CZK to account 238400856/0300."
    },
    "config": [],
    "banners": [],
    "parameters": [
      {
        "type": "AMOUNT",
        "id": "operation.amount",
        "label": "Amount",
        "valueFormatType": "AMOUNT",
        "formattedValue": "100.00 CZK",
        "amount": 100,
        "currency": "CZK",
        "currencyId": "operation.currency"
      },
      {
        "type": "KEY_VALUE",
        "id": "operation.account",
        "label": "To Account",
        "valueFormatType": "ACCOUNT",
        "formattedValue": "238400856/0300",
        "value": "238400856/0300"
      },
      {
        "type": "KEY_VALUE",
        "id": "operation.dueDate",
        "label": "Due Date",
        "valueFormatType": "DATE",
        "formattedValue": "Jun 29, 2019",
        "value": "2019-06-29"
      },
      {
        "type": "NOTE",
        "id": "operation.note",
        "label": "Note",
        "valueFormatType": "TEXT",
        "formattedValue": "Utility Bill Payment - 05/2019",
        "note": "Utility Bill Payment - 05/2019"
      },
      {
        "type": "BANK_ACCOUNT_CHOICE",
        "id": "operation.bankAccountChoice",
        "label": "From Your Account",
        "bankAccounts": [
          {
            "number": "12345678/1234",
            "accountId": "CZ4012340000000012345678",
            "name": "Běžný účet v CZK",
            "balance": 24394.52,
            "currency": "CZK",
            "usableForPayment": false,
            "unusableForPaymentReason": null
          },
          {
            "number": "87654321/4321",
            "accountId": "CZ4043210000000087654321",
            "name": "Spořící účet v CZK",
            "balance": 158121.1,
            "currency": "CZK",
            "usableForPayment": false,
            "unusableForPaymentReason": null
          },
          {
            "number": "44444444/1111",
            "accountId": "CZ4011110000000044444444",
            "name": "Spořící účet v EUR",
            "balance": 1.9,
            "currency": "EUR",
            "usableForPayment": false,
            "unusableForPaymentReason": "Low account balance"
          }
        ],
        "enabled": true,
        "defaultValue": "CZ4012340000000012345678"
      }
    ],
    "dynamicDataLoaded": true,
    "userInput": {
      "operation.bankAccountChoice": "CZ4012340000000012345678"
    }
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status" : "OK"
}

Update application context for an operation

Updates application context for an operation.

Method	`PUT`
Resource URI	`/operation/application`

Alternative with POST method for environments which do not allow PUT methods:

Method	`POST`
Resource URI	`/operation/application/update`

Request

Headers:
- Content-Type: application/json

{
  "requestObject": {
    "operationId": "3e87f071-2f08-4341-9034-47cb5f8a3fb4",
    "applicationContext": {
      "id": "BANK_ABC_PROD",
      "name": "Bank ABC",
      "description": "Authorization for Bank ABC",
      "originalScopes": ["SCOPE_1", "SCOPE_2", "SCOPE_3"],
      "extras": {
        "applicationOwner": "BANK_ABC"
      }
    }
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status" : "OK"
}

Update user for an operation

Updates user ID, organization ID and account status for an operation.

Method	`PUT`
Resource URI	`/operation/user`

Alternative with POST method for environments which do not allow PUT methods:

Method	`POST`
Resource URI	`/operation/user/update`

Request

Headers:
- Content-Type: application/json

{
  "requestObject": {
    "operationId": "0a044408-aea0-433a-80cf-6371dc2a76c0",
    "userId": "12345678",
    "organizationId": "RETAIL",
    "accountStatus": "ACTIVE"
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status" : "OK"
}

Set chosen authentication method

Sets chosen authentication method for current operation step.

Method	`PUT`
Resource URI	`/operation/chosenAuthMethod`

Alternative with POST method for environments which do not allow PUT methods:

Method	`POST`
Resource URI	`/operation/chosenAuthMethod/update`

Request

Headers:
- Content-Type: application/json

{
  "requestObject": {
    "operationId": "3e87f071-2f08-4341-9034-47cb5f8a3fb4",
    "chosenAuthMethod": "POWERAUTH_TOKEN"
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status" : "OK"
}

Update mobile token status for an operation

Set whether mobile token is active for an operation.

Method	`PUT`
Resource URI	`/operation/mobileToken/status`

Alternative with POST method for environments which do not allow PUT methods:

Method	`POST`
Resource URI	`/operation/mobileToken/status/update`

Request

Headers:
- Content-Type: application/json

{
  "requestObject": {
    "operationId": "1ee2d165-1926-4a77-be5f-82ec26f12b97",
    "mobileTokenActive": true
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status" : "OK"
}

Get mobile token configuration

Get whether mobile token is enabled for given user ID, operation name and authentication method.

Method	`POST`
Resource URI	`/operation/mobileToken/config/detail`

Request

Headers:
- Content-Type: application/json

{
  "requestObject": {
    "userId": "12345678",
    "operationName": "login",
    "authMethod": "LOGIN_SCA"
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "mobileTokenEnabled": true
  }
}

Store result of an AFS action

Store result of an AFS action for an operation.

Method	`POST`
Resource URI	`/operation/afs/action/create`

Request

Headers:
- Content-Type: application/json

{
  "requestObject": {
    "operationId": "47a74437-83f9-4567-8c9e-270bea98d9de",
    "afsAction": "APPROVAL_INIT",
    "stepIndex": 1,
    "requestAfsExtras": "{}",
    "afsResponseApplied": true,
    "afsLabel": "1FA",
    "responseAfsExtras": "{}",
    "timestampCreated": 1572618429867
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status" : "OK"
}

List operation configurations

Retrieves list of operation configurations.

Method	`POST`
Resource URI	`/operation/config/list`

Request

Headers:
- Content-Type: application/json

{
  "requestObject": {
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "operationConfigs": [
      {
        "operationName": "authorize_payment",
        "templateVersion": "A",
        "templateId": 1,
        "mobileTokenMode": "{\"type\":\"2FA\",\"variants\":[\"possession_knowledge\",\"possession_biometry\"]}"
      },
      {
        "operationName": "authorize_payment_sca",
        "templateVersion": "A",
        "templateId": 1,
        "mobileTokenMode": "{\"type\":\"2FA\",\"variants\":[\"possession_knowledge\",\"possession_biometry\"]}"
      },
      {
        "operationName": "login",
        "templateVersion": "A",
        "templateId": 2,
        "mobileTokenMode": "{\"type\":\"2FA\",\"variants\":[\"possession_knowledge\",\"possession_biometry\"]}"
      },
      {
        "operationName": "login_sca",
        "templateVersion": "A",
        "templateId": 2,
        "mobileTokenMode": "{\"type\":\"2FA\",\"variants\":[\"possession_knowledge\",\"possession_biometry\"]}"
      }
    ]
  }
}

Get operation configuration detail

Get operation configuration detail.

Method	`POST`
Resource URI	`/operation/config/detail`

Request

Headers:
- Content-Type: application/json

{
  "requestObject": {
    "operationName": "login"
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "operationName": "login",
    "templateVersion": "A",
    "templateId": 2,
    "mobileTokenMode": "{\"type\":\"2FA\",\"variants\":[\"possession_knowledge\",\"possession_biometry\"]}"
  }
}

Organizations

List organizations

Lists all organizations configured on the server.

Method	`POST`
Resource URI	`/organization/list`

Request

Headers:
- Content-Type: application/json

{
  "requestObject": {
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "organizations": [
      {
        "organizationId": "RETAIL",
        "displayNameKey": "organization.retail",
        "orderNumber": 1,
        "default": true
      },
      {
        "organizationId": "SME",
        "displayNameKey": "organization.sme",
        "orderNumber": 2,
        "default": false
      }
    ]
  }
}

Organization detail

Get detail of an organization configured on the server.

Method	`POST`
Resource URI	`/organization/detail`

Request

Headers:
- Content-Type: application/json

{
	"requestObject": {
		"organizationId": "RETAIL"
	}
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "organizationId": "RETAIL",
    "displayNameKey": "organization.retail",
    "orderNumber": 1,
    "default": true
  }
}

Last updated on Jul 20, 2020 (15:54) Edit on Github Send Feedback