Skip to main content
Skip table of contents

Initiate a Payment from an Account - no Web Form (Licensed Customers Only)

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 payment

To initiate a Direct Debit, trigger Create direct debit endpoint. Provide accountId of an imported account to indicate the sender account.

CODE 
POST /payments/directDebits

To initiate a SEPA Credit Transfer or SEPA Instant Credit Transfer, trigger Create money transfer endpoint. Provide accountId of an imported account to indicate the sender account.

CODE 
POST /payments/moneyTransfers

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 payment

Execute Submit payment service:

CODE 
POST /payments/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 the authorisation with the Decoupled SCA approach, where users could authenticate and authorise a transaction via the mobile app or an authorisation 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 payment submission.

If you are not familiar with the interfaces which are 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 payment

Mandatory request fields

  • paymentID

  • 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 payment along with the user bank credentials if they are required by the bank interface.

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

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

Step #2
Receive a redirect URL

How to recognise 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 the end-user 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 required on 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 /payments/moneyTransfers",
  "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 payment

Mandatory request fields

  • all fields from the previous request

  • hash

  • redirectCallback

    • the whole query string received on a step #4

Explanation

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

 

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

{
  "paymentId": 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
Bank connection

The API completes the payment initiation process and returns a bank connection resource.

CODE 
HTTP/1.1 201

{
  "id": 46,
  "bankId": 280002,
  "name": null,
  "bankingUserId": null,
  "bankingCustomerId": null,
  "bankingPin": null,
  "type": "ONLINE",
  "updateStatus": "IN_PROGRESS",
  "categorizationStatus": "READY",
  ...
}

Embedded approach

Step

Request/response example

Step #1
Submit payment

Mandatory request fields

  • paymentId

  • interface

  • loginCredentials

    • if the chosen bank interface has any items in

    loginCredentials field

Explanation

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

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

{
  "paymentId": 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 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": "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": "/payments/moneyTransfers",
  "authContext": "1/18",
  "bank": "DEMO0001- FinAPI Test Bank"
}

Step #3
Submit payment
(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. Value of hash field points to the original request.

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

{
  "paymentId": 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 recognise 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 /payments/submit",
  "authContext": "2/1534168",
  "bank": "DEMO0001 - finAPI Test Bank"
}

 

Step #5
Submit Payment

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. Value of hash field points to the original request.

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

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

Step #6
Payment submission result

The API completes the payment initiation process and returns a payment resource.

CODE 
HTTP/1.1 200

{
  "id": 1,
  "accountId": 111111100,
  "type": "MONEY_TRANSFER",
  "amount": 99.99,
  "orderCount": 1,
  "status": "SUCCESSFUL",
  "bankMessage": "Success",
  "requestDate": "2021-10-11 16:18:53.000",
  "executionDate": "2021-10-11 16:28:17.000"
}

Decoupled Approach

Step

Request/response example

Step #1
Submit payment

Mandatory request fields

  • paymentId

  • interface

  • loginCredentials

    • if the chosen bank interface has any items in

    loginCredentials field

Explanation

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

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

{
  "paymentId": 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 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 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": "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 /payments/moneyTransfers",
  "authContext": "1/18",
  "bank": "DEMO0001- FinAPI Test Bank"
}

Step #3
Submit payment
(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. Value of hash field points to the original request.

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

{
  "paymentId": 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 recognise 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 /payments/moneyTransfers",
  "authContext": "1/18",
  "bank": "DEMO0001 - finAPI Test Bank"
}

Step #5
Submit payment

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 /payments/moneyTransfers HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <user's access token>

{
  "paymentId": 277672,
  "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 /payments/moneyTransfers",
  "authContext": "1/18",
  "bank": "DEMO0001 - finAPI Test Bank"
}

Step #6
Payment submission result

The API completes the payment initiation process and returns a payment resource.

CODE 
HTTP/1.1 200

{
  "id": 1,
  "accountId": 111111100,
  "type": "MONEY_TRANSFER",
  "amount": 99.99,
  "orderCount": 1,
  "status": "SUCCESSFUL",
  "bankMessage": "Success",
  "requestDate": "2021-10-11 16:18:53.000",
  "executionDate": "2021-10-11 16:28:17.000"
}

Step 3 - Get the Payment status (Optional)

If upon completion of the steps described in Step 2 above, the status of the payment initiation is still PENDING, there is a chance that the bank has not returned the final payment status yet or there was an error when trying to obtain the payment initiation status. 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 payments to obtain the latest payment status.

JavaScript errors detected

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

If this problem persists, please contact our support.

Contact Support Close