|
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). |
0 commit comments