# Usage ### Creating an API context In order to start making calls with the bunq API, you must first register your API key and device, and create a session. In the SDKs, we group these actions and call it "creating an API context". The context can be created by using the following code snippet: ```java ApiContext apiContext = ApiContext.create( ApiEnvironmentType.SANDBOX, sandboxUser.getApiKey(), "Your Device Description" ); apiContext.save("bunq-config.conf"); BunqContext.loadApiContext(apiContext); //load the API context to use in your app ``` {% hint style="warning" %} **Please note:** initialising your application is a heavy task and it is recommended to do it only once per device. {% endhint %} **PSD2** 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. 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: * Up to 64 characters * PISP and/or AISP used in the end. Make sure you have your unique eIDAS certificate number and certificates ready when you want to perform these tasks on our production environment. Creating a PSD2 context is very easy: ```java ApiContext apiContext = ApiContext.createForPsd2( ENVIRONMENT_TYPE, SecurityUtils.getCertificateFromFile(PATH_TO_CERTIFICATE), SecurityUtils.getPrivateKeyFromFile(PATH_TO_PRIVATE_KEY), new Certificate[]{ SecurityUtils.getCertificateFromFile(PATH_TO_CERTIFICATE_CHAIN) }, DESCRIPTION ) ``` 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. For a more detailed example, check the [tinker\_java](https://github.com/bunq/tinker_java/) repository. **Safety considerations** The file storing the context details (i.e. `bunq.conf`) is a key to your account. Anyone having access to it is able to perform any Public API actions with your account. Therefore, we recommend choosing a truly safe place to store it. #### Making API calls 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`. 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. Before you make a call, make sure that you have loaded `ApiContext` in to the `BunqContext`. ### Core Functionalities #### Managing Monetary Accounts **Create a new monetary account:** ```java // Create a new EUR bank account with a description Integer accountId = MonetaryAccountBankApiObject.create( "EUR", // Currency code "Account Description" // Description for the account ).getValue(); // Returns the new account ID ``` **Close a monetary account:** ```java // Close an existing monetary account MonetaryAccountBankApiObject.update( accountId, // ID of the account to close null, // No change to currency null, // No change to description null, // No change to daily limit "CANCELLED", // New status for the account "REDEMPTION_VOLUNTARY", // Sub-status explaining the closure reason "OTHER", // Reason category "Reason description" // Detailed explanation ); ``` #### Payments **Make a payment to another user:** ```java // Create the amount object with value and currency AmountObject amount = new AmountObject("0.01", "EUR"); // Amount in EUR // Create pointer object to specify the recipient PointerObject recipient = new PointerObject( "EMAIL", // Type of identifier (EMAIL, PHONE_NUMBER, IBAN) "recipient@example.com" // The actual identifier value ); // Execute the payment PaymentApiObject.create( amount, // The amount to transfer recipient, // Who to pay "Payment description" // Description shown on the transaction ); ``` **Batch payments:** ```java // Create a list to hold multiple payments List payments = new ArrayList<>(); // Add payments to the list payments.add(new PaymentApiObject( new AmountObject("0.01", "EUR"), // Amount for this payment recipient, // Recipient for this payment "Payment description" // Description for this payment )); // Execute all payments as a batch PaymentBatchApiObject.create(payments); // More efficient than individual calls ``` #### Payment Requests **Create a payment request:** ```java // Request money from another user RequestInquiryApiObject.create( new AmountObject("0.01", "EUR"), // Amount to request recipient, // Who to request from "Request description", // Description of request false, // Allow bunqme - false means regular request monetaryAccountId // ID of account to receive the money ); ``` **Accept a payment request:** ```java // Create parameters to filter for pending requests Map params = new HashMap<>(); params.put("status", "PENDING"); // Only get PENDING requests // Retrieve pending requests List requests = RequestResponseApiObject.list( monetaryAccountId, // Account ID to check for requests params // Filter parameters ).getValue(); // Accept the first pending request RequestResponseApiObject.update( requests.get(0).getId(), // ID of the request to update monetaryAccountId, // Account ID that received the request null, // No counter-amount needed "ACCEPTED" // New status - ACCEPTED or REJECTED ); ``` #### Card Management **Get possible card names:** ```java // Get all available card names List cardNames = CardNameApiObject.list().getValue(); // Get the array of possible names for the first card type List possibleNames = cardNames.get(0).getPossibleCardNameArray(); ``` **Order a new card:** ```java // Generate a random string for the second line on the card String secondLine = generateRandomSecondLine(); // Custom method to generate text String nameOnCard = "YOUR NAME"; // Name to be printed on the card // Order a new debit card CardDebitApiObject.create( secondLine, // Text for second line on card nameOnCard, // Name to appear on card "MASTERCARD", // Card type "MASTERCARD_DEBIT" // Product type ); ``` #### File Attachments **Upload a public attachment:** 
// Create headers for the attachment
HashMap<String, String> headers = new HashMap<>();
BunqHeader.CONTENT_TYPE.addTo(headers, "image/png");  // Specify file type
BunqHeader.ATTACHMENT_DESCRIPTION.addTo(headers, "Description");  // Add description

// Read file into byte array
byte[] fileContents = FileUtils.readFileToByteArray(new File("path/to/file.png"));

// Upload the attachment and get its UUID
String uuid = AttachmentPublicApiObject.create(headers, fileContents).getValue();
**Retrieve an attachment:** ```java // Download attachment content using its UUID byte[] fileContents = AttachmentPublicContentApiObject.list(uuid).getValue(); ``` #### Avatar Management **Create an avatar:** ```java // First upload an image as a public attachment String attachmentUuid = uploadAttachment(); // Custom method to upload attachment // Then create an avatar with the attachment String avatarUuid = AvatarApiObject.create(attachmentUuid).getValue(); // Returns avatar UUID ``` #### Session Management **Delete the current session:** ```java // Delete current session (0 is a dummy session ID, as the actual ID isn't needed) SessionApiObject.delete(0).getValue(); // Will invalidate current session ``` **Reset a session:** ```java // Reset the session in your API context apiContext.resetSession(); // Creates a new session apiContext.save("bunq-config.conf"); // Save changes to configuration file ``` #### Notification Filters (Webhooks) **Create a URL notification filter for a monetary account:** ```java // Create a filter for payment mutations (changes) with a callback URL NotificationFilterUrlObject filter = new NotificationFilterUrlObject( "MUTATION", // Event category to trigger on "https://your-callback-url.com" // URL to receive webhooks ); // Add filter to a list (API expects a list) List filters = new ArrayList<>(); filters.add(filter); // Set up the notification filter for a specific account NotificationFilterUrlMonetaryAccountInternal.createWithListResponse( monetaryAccountId, // Account to monitor filters // List of filters to apply ); ``` **Create a push notification filter for a user:** ```java // Create a filter for push notifications about payment mutations NotificationFilterPushObject filter = new NotificationFilterPushObject("MUTATION"); // Add filter to a list (API expects a list) List filters = new ArrayList<>(); filters.add(filter); // Set up the push notification filter for the current user NotificationFilterPushUserInternal.createWithListResponse(filters); ``` #### OAuth Authorization **Create an OAuth authorization URI:** ```java // Generate an OAuth URL for authorization String uri = OauthAuthorizationUri.create( OauthResponseType.CODE, // Request an authorization code "your-redirect-uri", // Where to redirect after authorization new OauthClientApiObject("status"), // Client information "state" // Security state parameter ).getAuthorizationUri(); // Get the complete URI ``` **Creating objects** With the `create` method you can create new models. This method normally returns the `id` of the created model. ```java Payment.create( new Amount(amount, CURRENCY_EURO), new Pointer(POINTER_TYPE_EMAIL, recipient), description ); ``` **Reading objects** Reading objects can be done via the `get` or `list` method. These type of calls always returns the model or binary data. ```java Payment.list( monetaryAccountBank.getId(), pagination.getUrlParamsCountOnly() ) ``` **Updating objects** 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. The `update` method will also normally return the `Id` of the updated model. ```java MonetaryAccountBank.update(Integer.parseInt(accountId), name); ``` **Deleting objects** Deleting object can be done via the `delete` method. This method also requires the object identifier which could be an `Id` or `uuid`. This method normally returns an empty response. ```java CustomerStatementExport.delete(customerStatementId); ``` ### Tips for Using the SDK 1. Always ensure your API context is properly loaded before making API calls 2. Request spending money in the sandbox environment when needed: ```java // Check if account has less than 10 units of currency if (Float.parseFloat(monetaryAccountBank.getBalance().getValue()) < 10) { // Request money from the sandbox sugar daddy account RequestInquiryApiObject.create( new AmountObject("500", "EUR"), new PointerObject("EMAIL", "sugardaddy@bunq.com"), "Request description", false ); } ``` 3. Save your API context after making changes to it 4. Remember to refresh your context periodically for long-running applications: ```java // Refresh the user context to get latest information BunqContext.getUserContext().refreshContext(); ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://doc.bunq.com/getting-started/tools/unmaintained-software-development-kits-sdks/java/usage.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.