SDK update: connect and authorize as a PSD2 user in 10 minutes

We are excited to share you don’t have to search for the right way to connect to our sandbox as a PSD2 user anymore! 🙌🌈 We have updated our SDKs with code that will help you to pass the registration and authorization stages of the PSD2 flow in 10 minutes.

Moreover, we ourselves have used the SDKs to create an example implementation for you. And we made it much easier to create test certificates 🎉.

The C# SDK was the most requested update, so we started with that one. We will update the other SDKs shortly.

Let’s get to the details of the update!

What’s new

We considered and covered every step you need to take to create an API context and authorize into user accounts. Let’s look at these steps (and the solutions we offer) one by one.

0. Create a test certificate and other required values

Before you pass your certificate, you need to have one. You will also need a private key and a certificate chain. Use the command below to generate the first two.

In real life, you will get a certificate chain along with the eIDAS certificate. Here’s a sample certificate you can use as a chain in the bunq test environment:

1. Register the certificate and create an API context

The SDKs shorten the whole sequence of API context creation steps into one command. Here we compare two ways of running the same flow:

SDK:

1. Run ApiContext.CreateForPsd2 passing in the test certificate, your private key and the certificate chain. This will do the whole request sequence as described below.
2. Load the received API context with BunqContext.LoadApiContext.

HTTP requests:

1. Execute POST v1/installation → Get your installation Token and the server public key.
2. Pass the test certificate, the certificate chain and the installation Token when calling POST v1/payment-service-provider-credential. → Receive your API key in return. You’ll need it to start an OAuth flow.
3. Register your device via POST v1/device-server using the API key for the secret and passing the installation Token in the X-Bunq-Client-Authentication header.
4. Create an introductory session by executing POST v1/session-server. This will activate your API key. Provide the installation Token in the X-Bunq-Client-Authentication header → Receive a session Token and use it in the X-Bunq-Client-Authentication at the next stage.

2. Set up OAuth

Unlike with creating an API context, starting an OAuth authorization via the SDKs isn’t different from the direct API usage.

SDK:

1. Create an OAuth client if needed using OauthClient.Create(“ACTIVE”).
2. Get the OAuth client via OauthClient.Get(id) → Receive your Client ID and Client Secret.
3. Add a callback with OauthCallbackUrl.Create(oauthClientId, redirectUri)

HTTP requests:

1. Call POST /v1/user/{userID}/oauth-client
2. Call GET /v1/user/{userID}/oauth-client/{oauth-clientID}. → Receive your Client ID and Client Secret.
3. Call POST /v1/user/{userID}/oauth-client/{oauth-clientID}/callback-url. Include the OAuth callback URL of your application.

3. Install the sandbox app and create a sandbox user

This step requires using our sandbox app. From there, you can test any flow you need your users to follow.

1. Download and install the sandbox bunq Android APK.
2. Create a sandbox user using Tinker:

• run bash <(curl -s https://tinker.bunq.com/php/setup.sh) in an empty folder;
• run php tinker/user-overview.php and get a phone number, login code and confirmation code in the output;
• log in using this information.

The created account will have €500 of sandbox money on it by default. If you need more funds, send a request to sugardaddy@bunq.com from the sandbox app.

4. Authorize into a test user account

Authorization is not covered in the SDKs. The good news is, it’s not that big of a hassle.

1. Create an oauth authorization request: https://oauth.sandbox.bunq.com/auth?response_type=code&client_id={client_id}&redirect_uri={callback/redirect URL}.
2. Click on it as the test user would from within your application and scan the QR code that appears afterwards. The browser will redirect to your callback URL with a logic code set.
3. Use the code to make a POST call to https://api-oauth.sandbox.bunq.com/v1/token?grant_type=authorization_code&code={code}&redirect_uri={redirectUrl}&client_id={client_Id}&client_secret={secret}
4. You’ll receive an object with an access_token. You can use the token as an API key to interact with the user account for 90 days. After the 90-day period ends, you’ll need to repeat the steps in this section.

SDK use example

As promised, we ate our own dog food 🐶 and used the C# SDK to build a sample implementation of the PSD2 registration, OAuth, and authorization.

We are excited to hear your feedback on the SDK update! Was it easy to create and use a test eIDAS certificate? Did the example help? Share your stories in the comments below.