Skip to main content
Skip table of contents

Initiate a Standalone Standing Order- no Web Form (Licensed Customers Only)

To be able to use your PSD2 license with the finAPI APIs, please refer to the necessary steps to register the certificate with us and complete the TPP registration of the banks to which you plan to connect.

For more information, please refer to Licensed customers

Pre-requisites

Step 1 - Create a standing order

To initiate a SEPA Standing Order, trigger Create standing order endpoint. Provide IBAN to indicate the sender account.

CODE 
POST /standingOrders

There are some payment data validations that we recommend being implemented to avoid bank payment rejections. Please refer to Payment Data Validation.

Step 2 - Submit standing order

Execute Submit standing order service:

CODE 
POST /standingOrders/submit

The payload and the flow varies based on the SCA approach offered by the bank (in the API: properties of the bank interface (bank.interface.properties).

Some banks have implemented the Embedded SCA approach, where the user credentials and the second factor can be submitted to the bank via the TPP.

Some banks will require a redirect to the bank server to complete the authentication and second-factor verification, this is the so-called Redirect SCA.

Some banks allow authorization with the Decoupled SCA approach, where users could authenticate and authorize a transaction via the mobile app or an authorization device.

The combination of different SCA approaches is also possible. For example Embedded + Decoupled: a user will provide the login credentials to a TPP and then a push notification will be sent to the mobile application.

Please make sure your application can dynamically handle all variations.

Please refer to the API specification for more details.

It is mandatory to indicate the interface that should be used for the standing order submission.

If you are unfamiliar with the interfaces supported by finAPI, please check Interfaces .

Please see below the examples of the flows for each SCA approach: Redirect, Embedded, and Decoupled.

Redirect approach

Step

Request/response example

Step #1
Submit standing order

Mandatory request fields

  • standingOrderId

  • interface

  • redirectUrl

    • URL of the client’s endpoint that handles a redirect from the bank

  • loginCredentials

    • if the chosen bank interface has any items in

    loginCredentials field

Explanation

The client application submits the standing order along with the user bank credentials if they are required by the bank interface.

CODE 
POST /standingOrders/submit HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <user's access token>

{
  "standingOrderId": 1,
  "interface": "XS2A",
  "redirectUrl": "https://customer1.io",
  "loginCredentials": [
    {
      "label": "Onlinebanking-ID",
      "value": "idontexist"
    }
  ]
}

Step #2
Receive a redirect URL

How to recognize the step

Field errors.multiStepAuthentication.status has REDIRECT_REQUIRED value.

Mandatory response fields of multiStepAuthentication object:

  • hash

  • status

  • redirectUrl

  • redirectContext

  • redirectContextField

Explanation

The API builds a redirect URL that will route tenuserser to a page on the bank side, where the user can complete the authentication process. In this step, the client’s application should store values from redirectContext and redirectContextField fields internally, as they will be requiredinn the subsequent steps.

CODE 
HTTP/1.1 510 

{
  "errors": [
    {
      "message": null,
      "code": "ADDITIONAL_AUTHENTICATION_REQUIRED",
      "type": "BUSINESS",
      "multiStepAuthentication": {
        "hash": "288c0a78c6596e8f02f70a21e731d46a",
        "status": "REDIRECT_REQUIRED",
        "challengeMessage": null,
        "answerFieldLabel": null,
        "redirectUrl": "https://demobank.finapi.io?state=976641d2-c03f-4919-8dac-16ccfd24b4e0",
        "redirectContext": "976641d2-c03f-4919-8dac-16ccfd24b4e0",
        "redirectContextField": "state",
        "twoStepProcedures": null,
        "photoTanMimeType": null,
        "photoTanData": null,
        "opticalData": null
      }
    }
  ],
  "date": "2019-11-27 11:20:21.261",
  "requestId": "selfgen-fece3d6c-a0f0-43ea-a910-7e9ca7a7b1f6",
  "endpoint": "POST /standingOrders/submit",
  "authContext": "1/18",
  "bank": "DEMO0002 - finAPI Test Redirect Bank"
}

Step #3
Redirect to bank

The client application should redirect the end-user to the given redirectUrl.

Example

CODE 
GET https://demobank.finapi.io?state=976641d2-c03f-4919-8dac-16ccfd24b4e0 HTTP/1.1

Step #4
Redirect back

When the end-user successfully completes the authentication process on the bank’s side, he is redirected to the URL given in step #1. Additionally, the bank adds some more data to the URL (as query parameters). But the most important part for the client application is this state parameter (generally speaking, the name of the parameter is provided in step #2 as a value of redirectContextField field): the client application can use its value to recognize the end-user that was redirected by the bank - the value should match the one given on a step #2 in redirectContext field.

Example

CODE 
GET https://customer1.io?state=976641d2-c03f-4919-8dac-16ccfd24b4e0&code=1e065516-0e9a-4f53-b5a6-140e69a3bf70 HTTP/1.1

Step #5
Submit standing order

Mandatory request fields

  • all fields from the previous request

  • hash

  • redirectCallback

    • the whole query string received on step #4

Explanation

The client application submits a query string as a value of the redirectCallback field. The API processes the given string, extracts required data, and continues the authentication process.

 

CODE 
POST /standingOrders/submit HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <user's access token>

{
  "standingOrderId": 1,
  "interface": "XS2A",
  "redirectUrl": "https://customer1.io",
  "loginCredentials": [
    {
      "label": "Onlinebanking-ID",
      "value": "idontexist"
    }
  ],
  "multiStepAuthentication": {
    "hash": "288c0a78c6596e8f02f70a21e731d46a",
    "redirectCallback": "state=976641d2-c03f-4919-8dac-16ccfd24b4e0&code=1e065516-0e9a-4f53-b5a6-140e69a3bf70"
  }
}

Step #6
Standing Order submission result

The API completes the standing order initiation process and returns a bank standing order resource.

CODE 
HTTP/1.1 200

{
id: 1,
accountId: 1,
iban: "string",
amount: 99.99,
currency: "EUR",
startDate: "2023-01-01 00.00.00.000",
endDate: "2023-01-01 00.00.00.000",
frequency: "MONTHLY",
dayOfExecution: 31,
requestDate: "2019-01-01 00:00:00.000",
requestCompletionDate: "2019-01-01 00:00:00.000",
status: "OPEN",
bankMessage: "string"
}

Embedded approach

Step

Request/response example

Step #1
Submit standing order

Mandatory request fields

  • standingOrderId

  • interface

  • loginCredentials

    • if the chosen bank interface has any items in

    loginCredentials field

Explanation

The client application submits the standing order along with the user bank credentials if they are required by the bank interface.

CODE 
POST /standingOrders/submit HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <user's access token>

{
  "standingOrderId": 1,
  "interface": "XS2A",
  "loginCredentials": [
    {
      "label": "Onlinebanking-ID",
      "value": "demo"
    },
    {
      "label": "PIN",
      "value": "demo"
    }
  ]
}

Step #2
Receive a list of two step procedures
(an optional step)

How to recognize the step

Field errors.multiStepAuthentication.status has TWO_STEP_PROCEDURE_REQUIRED value.

Mandatory response fields of multiStepAuthentication object:

  • hash

  • status

  • twoStepProcedures

Explanation

If the bank decides, it responds with a list of available two-step procedures (aka SCA methods - Strong Customer Authentication methods). And then the client application should ask the end-user to choose one of the offered two-step procedures.

CODE 
HTTP/1.1 510

{
  "errors": [
    {
      "message": "SCA method selection is required",
      "code": "ADDITIONAL_AUTHENTICATION_REQUIRED",
      "type": "BUSINESS",
      "multiStepAuthentication": {
        "hash": "651d37f0aeb5f326bc5ed60a404d8a72",
        "status": "TWO_STEP_PROCEDURE_REQUIRED",
        "challengeMessage": null,
        "answerFieldLabel": null,
        "redirectUrl": null,
        "redirectContext": null,
        "redirectContextField": null,
        "twoStepProcedures": [
          {
            "procedureId": "DEMO-TSP-01",
            "procedureName": "SMS",
            "procedureChallengeType": "TEXT",
            "implicitExecute": false
          },
          {
            "procedureId": "DEMO-TSP-02",
            "procedureName": "PUSH",
            "procedureChallengeType": "TEXT",
            "implicitExecute": false
          }
        ],
        "photoTanMimeType": null,
        "photoTanData": null,
        "opticalData": null
      }
    }
  ],
  "date": "2019-11-27 08:13:32.155",
  "requestId": "selfgen-3c81395b-7e01-40d2-835e-300ba9af1399",
  "endpoint": "/standingOrders/submit",
  "authContext": "1/18",
  "bank": "DEMO0001- FinAPI Test Bank"
}

 

Step #3
Submit standing order
(an optional step)

Mandatory request fields

  • all fields from the previous request

  • multiStepAuthentication.hash

    • the value should be taken from the response on step #2

  • twoStepProcedureId

    • field

    procedureId of the chosen two-step procedure

Explanation

The client application asks the end-user to choose a two-step procedure and then submits it to the API. The value of the hash field points to the original request.

CODE 
POST /standingOrders/submit HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <user's access token>

{
  "standingOrderId": 1,
  "interface": "XS2A",
  "loginCredentials": [
    {
      "label": "Onlinebanking-ID",
      "value": "demo"
    },
    {
      "label": "PIN",
      "value": "demo"
    }
  ],
  "multiStepAuthentication": {
    "hash": "651d37f0aeb5f326bc5ed60a404d8a72",
    "twoStepProcedureId": "DEMO-TSP-01"
  }
}

 

Step #4
Receive an MSA challenge message

How to recognize the step

Field errors.multiStepAuthentication.status has CHALLENGE_RESPONSE_REQUIRED value.

Mandatory response fields of multiStepAuthentication object:

  • hash

  • status

  • the following fields are presented depending on the two-step procedure type:

    • for type = TEXT:

      • challengeMessage

    • for type = PHOTO:

      • photoTanMimeType

      • photoTanData

    • for type = FLICKER_CODE*:

      • opticalData

*Note: feel free to use the flicker code template prepared by finAPI: Flicker Code Template

Explanation

When the two-step procedure is chosen (either by the bank or by the end user), the API responds with details for the end user. The client application should show this info to the end-user and ask for an answer.

 

CODE 
HTTP/1.1 510

{
  "errors": [
    {
      "message": "An additional authentication is required. Please enter the following code: 123456",
      "code": "ADDITIONAL_AUTHENTICATION_REQUIRED",
      "type": "BUSINESS",
      "multiStepAuthentication": {
        "hash": "651d37f0aeb5f326bc5ed60a404d8a72",
        "status": "CHALLENGE_RESPONSE_REQUIRED",
        "challengeMessage": "An additional authentication is required. Please enter the following code: 123456",
        "answerFieldLabel": "TAN",
        "redirectUrl": null,
        "redirectContext": null,
        "redirectContextField": null,
        "twoStepProcedures": null,
        "photoTanMimeType": null,
        "photoTanData": null,
        "opticalData": null
      }
    }
  ],
  "date": "2021-10-11 16:20:12.744",
  "requestId": "selfgen-8b108042-6c2c-4724-b345-2bf983ab0659",
  "endpoint": "POST /standingOrders/submit",
  "authContext": "2/1534168",
  "bank": "DEMO0001 - finAPI Test Bank"
}

 

Step #5
Submit Standing Order

Mandatory request fields

  • all fields from the previous request

  • challengeResponse

    • the answer from the end-user

Explanation

The client application asks for the challenge response and submits it back to the API. The valuethe of hash field points to the original request.

CODE 
POST /standingOrders/submit HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <user's access token>

{
  "standingOrderId": 1,
  "interface": "XS2A",
  "loginCredentials": [
    {
      "label": "Onlinebanking-ID",
      "value": "demo"
    },
    {
      "label": "PIN",
      "value": "demo"
    }
  ],
  "multiStepAuthentication": {
    "hash": "651d37f0aeb5f326bc5ed60a404d8a72",
    "twoStepProcedureId": "DEMO-TSP-01",
    "challengeResponse": "123456"
  }
}

 

Step #6
Standing Order submission result

The API completes the standing order initiation process and returns a standing order resource.

CODE 
HTTP/1.1 200

{
id: 1,
accountId: 1,
iban: "string",
amount: 99.99,
currency: "EUR",
startDate: "2023-01-01 00.00.00.000",
endDate: "2023-01-01 00.00.00.000",
frequency: "MONTHLY",
dayOfExecution: 31,
requestDate: "2019-01-01 00:00:00.000",
requestCompletionDate: "2019-01-01 00:00:00.000",
status: "OPEN",
bankMessage: "string"
}

Decoupled Approach

Step

Request/response example

Step #1
Submit standing order

Mandatory request fields

  • standingOrderId

  • interface

  • loginCredentials

    • if the chosen bank interface has any items in

    loginCredentials field

Explanation

The client application submits the standing order along with the user bank credentials if they are required by the bank interface.

CODE 
POST /standingOrders/submit HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <user's access token>

{
  "standingOrderId": 1,
  "interface": "XS2A",
  "loginCredentials": [
    {
      "label": "Onlinebanking-ID",
      "value": "demo"
    },
    {
      "label": "PIN",
      "value": "demo"
    }
  ]
}

Step #2
Receive a list of ttwo-stepprocedures
(an optional step)

How to recognise the step

Field errors.multiStepAuthentication.status has TWO_STEP_PROCEDURE_REQUIRED value.

Mandatory response fields of multiStepAuthentication object:

  • hash

  • status

  • twoStepProcedures

Explanation

If the bank decides, it responses with a list of available two-step procedures (aka SCA methods - Strong Customer Authentication methods). And then the client application should ask the end-user to choose one of the offered two-step procedures.

CODE 
HTTP/1.1 510

{
  "errors": [
    {
      "message": "SCA method selection is required",
      "code": "ADDITIONAL_AUTHENTICATION_REQUIRED",
      "type": "BUSINESS",
      "multiStepAuthentication": {
        "hash": "112c3581b39fc95a1f979d0d73f14dfb",
        "status": "TWO_STEP_PROCEDURE_REQUIRED",
        "challengeMessage": null,
        "answerFieldLabel": null,
        "redirectUrl": null,
        "redirectContext": null,
        "redirectContextField": null,
        "twoStepProcedures": [
          {
            "procedureId": "DEMO-TSP-01",
            "procedureName": "SMS",
            "procedureChallengeType": "TEXT",
            "implicitExecute": false
          },
          {
            "procedureId": "DEMO-TSP-02",
            "procedureName": "PUSH",
            "procedureChallengeType": "TEXT",
            "implicitExecute": false
          }
        ],
        "photoTanMimeType": null,
        "photoTanData": null,
        "opticalData": null
      }
    }
  ],
  "date": "2019-11-27 08:13:32.155",
  "requestId": "selfgen-3c81395b-7e01-40d2-835e-300ba9af1399",
  "endpoint": "POST /standingOrders/submit",
  "authContext": "1/18",
  "bank": "DEMO0001- FinAPI Test Bank"
}

 

Step #3
Submit standing order
(an optional step)

Mandatory request fields

  • all fields from the previous request

  • multiStepAuthentication.hash

    • the value should be taken from the response on step #2

  • twoStepProcedureId

    • field

    procedureId of the chosen two-step procedure

Explanation

The client application asks the end-user to choose a two-step procedure and then submits it to the API. The value of the hash field points to the original request.

CODE 
POST /standingOrders/submit HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <user's access token>

{
  "standingOrderId": 1,
  "interface": "XS2A",
  "loginCredentials": [
    {
      "label": "Onlinebanking-ID",
      "value": "demo"
    },
    {
      "label": "PIN",
      "value": "demo"
    }
  ],
  "multiStepAuthentication": {
    "hash": "112c3581b39fc95a1f979d0d73f14dfb",
    "twoStepProcedureId": "DEMO-TSP-02"
  }
}

 

Step #4
Receive an error message that the decoupled approach is required

How to recognize the step

Field errors.multiStepAuthentication.status has DECOUPLED_AUTH_REQUIRED value.

Mandatory response fields of multiStepAuthentication object:

  • hash

  • status

  • challengeMessage

    • if any message was provided by the bank

Explanation

If the chosen two-step procedure was of a decoupled type, the API responds with this error. The client application should notify the end-user that the bank will send a notification.

CODE 
HTTP/1.1 510

{
  "errors": [
    {
      "message": "Bitte bestätigen Sie auf ihrem externen Gerät die Anmeldung",
      "code": "ADDITIONAL_AUTHENTICATION_REQUIRED",
      "type": "BUSINESS",
      "multiStepAuthentication": {
        "hash": "112c3581b39fc95a1f979d0d73f14dfb",
        "status": "DECOUPLED_AUTH_REQUIRED",
        "challengeMessage": "Bitte bestätigen Sie auf ihrem externen Gerät die Anmeldung",
        "answerFieldLabel": null,
        "redirectUrl": null,
        "redirectContext": null,
        "redirectContextField": null,
        "twoStepProcedures": null,
        "photoTanMimeType": null,
        "photoTanData": null,
        "opticalData": null
      }
    }
  ],
  "date": "2019-11-27 10:35:17.682",
  "requestId": "selfgen-9f035aca-d094-42d7-9285-a3eae9d5a4a9",
  "endpoint": "POST /standingOrders/submit",
  "authContext": "1/18",
  "bank": "DEMO0001 - finAPI Test Bank"
}

Step #5
Submit standing order

Mandatory request fields

  • all fields from the previous request

  • decoupledCallback

    • this is a boolean field that signals to the API that the end-user is already informed about the decoupled authorization and might have already approved it.

Explanation

The client application asks the API to check the status of the authentication process. Value of hash field points to the original request.

CODE 
POST /standingOrders/submit HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <user's access token>

{
  "standingOrderId": 1,
  "interface": "XS2A",
  "loginCredentials": [
    {
      "label": "Onlinebanking-ID",
      "value": "demo"
    },
    {
      "label": "PIN",
      "value": "demo"
    }
  ],
  "multiStepAuthentication": {
    "hash": "112c3581b39fc95a1f979d0d73f14dfb",
    "twoStepProcedureId": "DEMO-TSP-02",
    "decoupledCallback": true
  }
}

Step #6
Receive an error message that the decoupled authentication is still in progress
(an optional step)

How to recognise the step

Field errors.multiStepAuthentication.status has DECOUPLED_AUTH_IN_PROGRESS value.

Mandatory response fields of multiStepAuthentication object:

  • hash

  • status

Explanation

The API returns this error if the authentication is still not completed on the bank side. The client application should continue repeating step #5 while the API returns this error.

 

CODE 
HTTP/1.1 510

{
  "errors": [
    {
      "message": "Bitte bestätigen Sie auf ihrem externen Gerät die Anmeldung",
      "code": "ADDITIONAL_AUTHENTICATION_REQUIRED",
      "type": "BUSINESS",
      "multiStepAuthentication": {
        "hash": "112c3581b39fc95a1f979d0d73f14dfb",
        "status": "DECOUPLED_AUTH_IN_PROGRESS",
        "challengeMessage": "Bitte bestätigen Sie auf ihrem externen Gerät die Anmeldung",
        "answerFieldLabel": null,
        "redirectUrl": null,
        "redirectContext": null,
        "redirectContextField": null,
        "twoStepProcedures": null,
        "photoTanMimeType": null,
        "photoTanData": null,
        "opticalData": null
      }
    }
  ],
  "date": "2019-11-27 10:42:54.468",
  "requestId": "selfgen-5801b1be-0e09-4d2a-99a2-a748d7ee6d7e",
  "endpoint": "POST /standingOrders/submit",
  "authContext": "1/18",
  "bank": "DEMO0001 - finAPI Test Bank"
}

Step #6
Standing order submission result

The API completes the standing order initiation process and returns a standing order resource.

CODE 
HTTP/1.1 200

{
id: 1,
accountId: 1,
iban: "string",
amount: 99.99,
currency: "EUR",
startDate: "2023-01-01 00.00.00.000",
endDate: "2023-01-01 00.00.00.000",
frequency: "MONTHLY",
dayOfExecution: 31,
requestDate: "2019-01-01 00:00:00.000",
requestCompletionDate: "2019-01-01 00:00:00.000",
status: "OPEN",
bankMessage: "string"
}

Step 3 - Get the Standing Order initiation status (Optional)

If upon completion of the steps described in Step 2 above, the status of the standing order initiation is still PENDING, there is a chance that the bank has not returned the final standing order initiation status yet or there was an error when trying to obtain the standing order initiation status and several attempts will be made in the background to obtain it (for more details, please refer to How to get the payment initiation status).

You can call Get standing orders to obtain the latest standing order initiation status.

Step 4 - Delete User (Optional)

If for your use-case you do not need to save the user to re-use it later, we recommend that you delete the user once the standing order initiation has been finalized via Delete the authorized user endpoint:

CODE 
DELETE /users

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close