Payments Public Documentation
Payments Public Documentation
Breadcrumbs

Initiate a Standalone Payment- 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 payment

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

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.

Note: for Direct Debits initiation, please refer to Initiate a Payment from an Account - no Web Form (Licensed Customers Only) as standalone Direct Debit initiation is not supported.

Step 2 - Submit payment

Execute Submit payment service:

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 authorization with the Decoupled SCA approach, where users could authenticate and authorize 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 is able to 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.

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

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

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

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.

 

 
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 payment resource.

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

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.

 
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.

 
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/submit",
  "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.

 
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.

 

 
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/moneyTransfers/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.

 
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.

 
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

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.

 
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.

 
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/submit",
  "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.

 
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.

 
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/submit",
  "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.

 
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.

 

 
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/submit",
  "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.

 
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 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 payments to obtain the latest payment 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 payment initiation has been finalized via Delete the authorized user endpoint:

DELETE /users