Payment Initiation Service — Relying Party Developer Guide

OAuth 2.0 (grant type authorization code) is the technical foundation of the protocol. It is combined with further OAuth extensions, such as PKCE and OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens, to achieve an appropriate protection level.

The next step, just as in other flows, is to send the user through the OP (Bank) selection at the account chooser. Please refer to the base document for details.

As a result from the previous step, you will be provided with the Issuer URL of the chosen Bank. You now need to obtain the service configuration from the Service Configuration service.

To do that, send an HTTP GET request from your backend to the service configuration service URL, attaching the issuer URL in the iss parameter.

For the sandbox, the URL is as follows (here shown with an example issuer): https://api.sandbox.openbanking.verimi.cloud/service-configuration/v1/?iss=https://testidp.sandbox.openbanking.verimi.cloud/issuer/10000001

For production, the URL is the following: https://api.openbanking.verimi.de/service-configuration/v1/?iss={issuer_url}

The API returns an HTTP status code and the service configuration document.

If an error is indicated, a JSON document explaining the error is contained in the response body, e.g.: {"error":"invalid_request","error_description":"The issuer 'https://accounts.inactivetestbank.de' is not active"}

When a service configuration document is returned, it is of the following form:

First, you (or your OAuth library) need to retrieve the OAuth Configuration, or Authorization Server Metadata document. This document will tell you about the endpoints that you need to use in the following.

The URL of this document is created as follows:

{oauth_issuer_url}/.well-known/oauth-authorization-server

The pushed authorization request endpoint, authorization endpoint, and token endpoint URLs are used in the following.

The authorization request is sent as a Pushed Authorization Request Pushed Authorization Requests to the authorization server. That means that most of the parameters usually sent in the OAuth authorization request are sent in an MTLS-protected POST request to the backend of the authorization server instead.

This ensures that the data contained in the authorization request remains confidential and cannot be altered by the user or an attacker.

The parameters in the pushed authorization request are shown in the following:

This request contains the payment authorization details in the authorization_details parameter.

In the next step, you need to redirect the user’s browser to the authorization endpoint of the bank, passing the request_uri and client_id parameters.

Screen control is with the OP now which will guide your user through login and consent. The OP requires information about your app in the course of this flow. You therefore have to provide a privacy policy and may provide an optional terms of service document and label upon registration.

After successful authentication, authorization, and initiation of the payment, the OP will redirect (HTTP status code 302) your user to the {redirect_uri} given in the Authentication Request including the following request parameters:

Errors according to OAuth 2.0 Authorization Error Response and OAuth 2.0 Error Response may occur and must be handled. In case of an error the parameter error will deliver an error code with optional details in the parameter error_description.

The error codes invalid_request, invalid_authorization_details, unable_to_enforce_debtor_account and access_denied as listed above may occur as well.

If your app received a successful authentication response, your backend at {redirect_uri} needs to exchange the authorization code for an access token at the token_endpoint . The token request is a POST request with content type application/x-www-form-urlencoded and the following parameters:

The OP will respond with a JSON object, i.e., the response will contain the header Content-Type: application/json;charset=UTF-8.

The JSON object has the following attributes (and may have others)

The successful token response indicates that the payment was received by the bank and first technical checks have been completed.

Errors according to OAuth 2.0 Error Response, or OIDC 1.0 Token Error Response may occur and must be handled. In case of an error the returned JSON object will normally contain an error attribute.