Skip to content

Commit 678a432

Browse files
author
Pascal Wink
committed
update readme
1 parent fc4ae07 commit 678a432

File tree

2 files changed

+2
-186
lines changed

2 files changed

+2
-186
lines changed

‎README.md

Lines changed: 1 addition & 165 deletions
Original file line numberDiff line numberDiff line change
@@ -1,165 +1 @@
1-
# bunq Java SDK
2-
3-
## Introduction
4-
Hi developers!
5-
6-
Welcome to the bunq Java SDK! 👨‍💻
7-
8-
We're very happy to introduce yet another unique product: complete banking SDKs!
9-
Now you can build even bigger and better apps and integrate them with your bank of the free! 🌈
10-
11-
Before you dive into this brand new SDK, please consider:
12-
- Learning how bunq works and what objects you will work with by reading [the intro to our API](https://github.com/bunq/doc/blob/develop/README.md) 🤓
13-
- Checking out [our developer portal](https://developer.bunq.com/) 🙌
14-
- Grabbing your Production API key from [our developer portal](https://developer.bunq.com/) or the bunq app 🗝
15-
- Generating a Sandbox API key using [our developer portal](https://developer.bunq.com/) or [Tinker](https://www.bunq.com/developer) 🗝
16-
- Visiting [our forum](https://together.bunq.com/t/api) where you can share your creations,
17-
questions and experience 🎤
18-
19-
Give us your feedback, create pull requests, build your very own bunq apps and most importantly:
20-
have fun! 💪
21-
22-
This SDK is in **beta**. We cannot guarantee constant availability or stability.
23-
Thanks to your feedback we will make improvements on it.
24-
25-
## Installation
26-
To install the package, please follow the instructions corresponding to your build tool under "How to" on the package page on JitPack: https://jitpack.io/#bunq/sdk_java
27-
28-
## Usage
29-
30-
### Creating an API context
31-
In order to start making calls with the bunq API, you must first register your API key and device,
32-
and create a session. In the SDKs, we group these actions and call it "creating an API context". The
33-
context can be created by using the following code snippet:
34-
35-
```
36-
ApiContext apiContext = ApiContext.create(ENVIRONMENT_TYPE, API_KEY,
37-
DEVICE_DESCRIPTION);
38-
apiContext.save(API_CONTEXT_FILE_PATH);
39-
```
40-
41-
**Please note:** <u>initialising your application is a heavy task and it is recommended to do it only once per device.</u>
42-
43-
After saving the context, you can restore it at any time:
44-
45-
```
46-
ApiContext apiContext = ApiContext.restore(API_CONTEXT_FILE_PATH);
47-
BunqContext.loadApiContext(apiContext);
48-
```
49-
50-
**Tip:** both saving and restoring the context can be done without any arguments. In this case the context will be saved to/restored from the `bunq.conf` file in the same folder with your executable.
51-
52-
#### Example
53-
See [`tinker/load_api_context`](https://github.com/bunq/tinker_java/blob/b03cbc2b84f35de9721a4083843c4015665d67f8/src/main/java/com/bunq/tinker/libs/BunqLib.java#L96-L101)
54-
55-
##### PSD2
56-
It is possible to create an ApiContext as PSD2 Service Provider. Although this might seem a complex task, we wrote some helper implementations to get you started.
57-
You need to create a certificate and private key to get you started. Our sandbox environment currently accepts all certificates, if these criteria are met:
58-
- Up to 64 characters
59-
- PISP and/or AISP used in the end.
60-
61-
Make sure you have your unique eIDAS certificate number and certificates ready when you want to perform these tasks on our production environment.
62-
63-
Creating a PSD2 context is very easy:
64-
```java
65-
ApiContext apiContext = ApiContext.createForPsd2(
66-
ENVIRONMENT_TYPE,
67-
SecurityUtils.getCertificateFromFile(PATH_TO_CERTIFICATE),
68-
SecurityUtils.getPrivateKeyFromFile(PATH_TO_PRIVATE_KEY),
69-
new Certificate[]{
70-
SecurityUtils.getCertificateFromFile(PATH_TO_CERTIFICATE_CHAIN)
71-
},
72-
DESCRIPTION
73-
)
74-
```
75-
76-
This context can be saved the same way as a normal ApiContext. After creating this context, create an OAuth client to get your users to grant you access.
77-
For a more detailed example, check the [tinker_java](https://github.com/bunq/tinker_java/) repository.
78-
79-
#### Safety considerations
80-
The file storing the context details (i.e. `bunq.conf`) is a key to your account. Anyone having
81-
access to it is able to perform any Public API actions with your account. Therefore, we recommend
82-
choosing a truly safe place to store it.
83-
84-
### Making API calls
85-
There is a class for each endpoint. Each class has functions for each supported action. These actions can be `create`, `get`, `update`, `delete` and `list`.
86-
87-
When making calls, The `userId` and `monetaryAccountId` needed to make calls will be determined by the SDK it. When no `monetaryAccountId` has been passed, the SDK will use the first active monetary account it can find. This is normally the monetary account used for billing.
88-
89-
Before you make a call, make sure that you have loaded `ApiContext` in to the `BunqContext`.
90-
91-
#### Creating objects
92-
With the `create` method you can create new models. This method normally returns the `id` of the created model.
93-
94-
95-
```
96-
Payment.create(
97-
new Amount(amount, CURRENCY_EURO),
98-
new Pointer(POINTER_TYPE_EMAIL, recipient),
99-
description
100-
);
101-
```
102-
103-
##### Example
104-
See [`tinker/make_payment`](https://github.com/bunq/tinker_java/blob/cc41ff072d01e61b44bb53169edb80bde9620dc5/src/main/java/com/bunq/tinker/MakePayment.java#L46)
105-
106-
##### NotificationFilters / Callbacks
107-
**Note!** Due to an in internal change in the way we handle `NotificationFilters` (Callbacks), you should not use the default classes included in this SDK.
108-
Please make sure you make use of the associated `Internal`-classes. For example when you need `NotificationFilterUrlUser`, make use of `NotificationFilterUrlUserInternal`.
109-
You can use every method of these classes, except for the `create()` method. **Always use `createWithListResponse()` instead.**
110-
111-
##### Example
112-
```java
113-
NotificationFilterPushUserInternal.createWithListResponse(...)
114-
NotificationFilterUrlUserInternal.createWithListResponse(...)
115-
NotificationFilterUrlMonetaryAccountInternal.createWithListResponse(...)
116-
```
117-
#### Reading objects
118-
119-
Reading objects can be done via the `get` or `list` method.
120-
121-
These type of calls always returns the model or binary data.
122-
123-
```
124-
Payment.list(
125-
monetaryAccountBank.getId(),
126-
pagination.getUrlParamsCountOnly()
127-
)
128-
```
129-
130-
##### Example
131-
See [`tinker/get_all_payment`](https://github.com/bunq/tinker_java/blob/b03cbc2b84f35de9721a4083843c4015665d67f8/src/main/java/com/bunq/tinker/libs/BunqLib.java#L161-L164)
132-
133-
#### Updating objects
134-
Updating objects through the API goes the same way as creating objects, except that also the object to update identifier (ID or UUID) is needed.
135-
136-
The `update` method will also normally return the `Id` of the updated model.
137-
138-
```
139-
MonetaryAccountBank.update(Integer.parseInt(accountId), name);
140-
```
141-
142-
##### Example
143-
See [`tinker/update_monetary_account`](https://github.com/bunq/tinker_java/blob/b03cbc2b84f35de9721a4083843c4015665d67f8/src/main/java/com/bunq/tinker/UpdateAccount.java#L36)
144-
145-
#### Deleting objects
146-
147-
Deleting object can be done via the `delete` method. This method also requires the object identifier which could be an `Id` or `uuid`.
148-
149-
This method normally returns an empty response.
150-
151-
```
152-
CustomerStatementExport.delete(customerStatementId);
153-
```
154-
155-
## Running Examples
156-
157-
To have an idea on how the SDK works you can play around with the java tinker located at: https://github.com/bunq/tinker_java
158-
159-
## Running tests
160-
Information regarding the test cases can be found in the [README.md](./src/test/README.md)
161-
located in [test](/src/test).
162-
163-
## Exceptions
164-
The SDK can throw multiple exceptions. For an overview of these exceptions please
165-
take a look at [EXCEPTIONS.md](./src/main/java/com/bunq/sdk/exception/EXCEPTIONS.md)
1+
📚 For full documentation about this sdk, visit [doc.bunq.com](https://doc.bunq.com/getting-started/tools/software-development-kits-sdks/java/usage).

‎src/test/README.md

Lines changed: 1 addition & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1 @@
1-
## Introduction
2-
Hi developers!
3-
4-
Welcome to the bunq Java SDK integration tests. Currently we are not
5-
targeting the 100% test coverage, but rather want to be certain that the most
6-
common scenarios can run without any errors.
7-
8-
## Setup
9-
First create a certificate and key using this command
10-
11-
```
12-
openssl req -x509 -newkey rsa:4096 -keyout src/test/Resource/key.pem -out src/test/Resource/certificate.pem -days 365 -nodes -subj "/CN=SdkJavaTdas1123asdhjb/C=NL" && \
13-
echo -e "\n--- KEY ---\n" && cat src/test/Resource/key.pem && \
14-
echo -e "\n--- CERTIFICATE ---\n" && cat src/test/Resource/certificate.pem
15-
```
16-
17-
## Execution
18-
To run tests via IntelliJ IDEA, you must make sure that you've build the project with gradle.
19-
20-
Afterwards you can right click on the tests folders and should be able to run
21-
the tests cases form the IDE.
1+
📚 For full API Test documentation, visit [doc.bunq.com](https://doc.bunq.com/getting-started/tools/software-development-kits-sdks/java/tests).

0 commit comments

Comments
 (0)